> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.trevex.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.trevex.io/_mcp/server.

# Errors

Every error response has the same shape:

```json
{
  "statusCode": 400,
  "message": "A human-readable explanation of what went wrong."
}
```

## Status reference

| HTTP Status | Cause                                                                    |
| ----------- | ------------------------------------------------------------------------ |
| `200`       | Success (GET requests)                                                   |
| `201`       | Resource created successfully                                            |
| `400`       | Validation error, missing required field, wrong state, or internal error |
| `401`       | Missing API key                                                          |
| `403`       | Invalid API key                                                          |
| `404`       | Resource not found                                                       |
| `409`       | Duplicate non-declined KYB request for the same user and company         |
| `500`       | Server-side error (e.g. AWS credentials not configured)                  |

## Common scenarios

### 400 on `create_claim`

Most `400` responses are caused by:

* Missing `user_email`, `registered_company_name`, or `country_code`
* `auth_sign_nationality` not exactly 2 characters
* `country_code` not a valid ISO 3166-1 alpha-2 code

### 409 on `create_claim`

A KYB request for the same `user_email` + company combination already exists
and isn't in a `rejected` state. The response includes the existing `request_id`
and its current `status` so you can surface the right message to your user.

### 400 on `update_claim`

Either the KYB request isn't in `approved` status, or no updatable fields were
provided besides `request_id`.

### 400 on `resubmit_claim`

Only KYB requests with status `rejected` can be resubmitted.

## Retries

`5xx` responses are safe to retry with exponential backoff. `4xx` responses
indicate a client-side problem - fix the input before retrying.

## On the webhook side

Your webhook endpoint should return `401` when signature verification fails.
TREVEX will log the failure and retry with backoff - if your endpoint keeps
rejecting valid signatures, check that:

* You're using the **raw request body**, not a re-serialised JSON string
* You're using the correct webhook signing secret for this Project
* Your clock is within the 5-minute timestamp tolerance
* You're comparing with a constant-time function (Node: `crypto.timingSafeEqual`; Python: `hmac.compare_digest`)

See [Verifying signatures](/webhooks#verifying-signatures) for full examples.