> ## Documentation Index
> Fetch the complete documentation index at: https://developers.clara.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Handling

> HTTP status codes, Clara-specific error codes, and retry strategies for building resilient integrations.

## Error Response Format

All errors return a JSON body with at minimum a `message` field:

```json theme={null}
{
  "message": "Threshold exceeds company limit",
  "code": "B013"
}
```

Some endpoints return additional context in a `details` array or an `error` string field depending on the API version.

***

## HTTP Status Codes

| Code  | Meaning                                                                     | What to do                                                                                |
| ----- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `200` | Success                                                                     | —                                                                                         |
| `400` | Bad request — invalid parameters or missing required fields                 | Fix the request body or query parameters before retrying                                  |
| `401` | Unauthorized — missing, expired, or invalid Bearer token                    | Refresh your token and retry                                                              |
| `403` | Forbidden — valid token but insufficient permissions                        | Check the user role (requires Administrator or the relevant scope)                        |
| `404` | Not found — resource does not exist                                         | Verify the UUID or path parameter                                                         |
| `422` | Unprocessable entity — request is well-formed but fails business validation | Check the `code` field for the specific Clara error code                                  |
| `429` | Rate limit exceeded                                                         | Back off and retry with exponential backoff (see [Rate Limits](#rate-limits))             |
| `500` | Internal server error                                                       | Retry once after a short delay; if persistent, contact support                            |
| `511` | Network authentication required                                             | Your mTLS certificate is missing or not being sent — check your client cert configuration |

### Response body examples by status code

**400 — Bad request (invalid parameter)**

```json theme={null}
{
  "code": "VALIDATION_ERROR",
  "message": "Invalid date format: startDate must be YYYY-MM-DD",
  "timestamp": "2024-03-15T10:30:00Z"
}
```

**401 — Unauthorized (expired token)**

```json theme={null}
{
  "code": "UNAUTHORIZED",
  "message": "Unauthorized",
  "timestamp": "2024-03-15T10:30:00Z"
}
```

**403 — Forbidden (insufficient role)**

```json theme={null}
{
  "code": "FORBIDDEN",
  "message": "Access denied: insufficient permissions for this resource",
  "timestamp": "2024-03-15T10:30:00Z"
}
```

**404 — Not found**

```json theme={null}
{
  "code": "NOT_FOUND",
  "message": "Card with UUID '1614c41b-8eb4-4573-9262-8aff011224c5' not found",
  "timestamp": "2024-03-15T10:30:00Z"
}
```

**422 — Business validation failure**

```json theme={null}
{
  "code": "B013",
  "message": "Threshold exceeds company limit",
  "timestamp": "2024-03-15T10:30:00Z"
}
```

**500 — Internal server error**

```json theme={null}
{
  "code": "B033",
  "message": "Core service failure",
  "timestamp": "2024-03-15T10:30:00Z"
}
```

***

## Auth Errors (401 / 403)

### 401 — Token expired

Tokens have a finite lifetime (`expires_in` seconds). When one expires, every request returns `401`.

```json theme={null}
{ "message": "Unauthorized" }
```

**Fix:** Request a new token from `/oauth/token` and retry. In production, refresh proactively before expiry rather than waiting for a `401`.

### 401 — Missing certificate

If the mTLS handshake fails because no client certificate is presented:

```json theme={null}
{ "message": "Unauthorized" }
```

**Fix:** Ensure `--cert` and `--key` are included in every request. See [Troubleshooting](/troubleshooting) for certificate debugging steps.

### 403 — Insufficient role

A valid token from a user role that doesn't have access to the endpoint.

**Fix:** Confirm the API user has the `COMPANY_OWNER` or required role. Role requirements vary by endpoint.

***

## Business Error Codes

Clara API returns business-specific error codes for validation failures. These appear in the `code` or `message` field of the response body.

### Cards

| Code   | Message                                                                    | Cause                                                                                          | Fix                                                                                        |
| ------ | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| `B013` | Threshold exceeds company limit                                            | The card `threshold` exceeds the company's available credit line                               | Set a lower threshold or contact your Clara account team to review credit limits           |
| `B022` | User is not activated                                                      | The target user hasn't completed email verification or 2FA setup, or the user has been deleted | Verify the user is active in the Clara platform before issuing a card                      |
| `B033` | Core service failure                                                       | Internal processing failure                                                                    | Retry after a short delay; if persistent, contact [integration support](#support-contacts) |
| —      | This user already has a card in the creation queue. Try again in 2 minutes | Concurrent card creation for the same user is not allowed                                      | Wait for the in-progress creation to complete or timeout (\~2 min) before retrying         |

### Users

| Scenario              | Status | Cause                                                                                   |
| --------------------- | ------ | --------------------------------------------------------------------------------------- |
| Tax ID format invalid | `400`  | Tax ID must match country format: MX = 11 or 13 chars, BR = 11 digits, CO = 7–10 digits |
| Duplicate email       | `400`  | A user with that email already exists in the company                                    |

### Transactions / Filtering

| Scenario                | Status | Cause                                                                     |
| ----------------------- | ------ | ------------------------------------------------------------------------- |
| Invalid date format     | `400`  | Dates must be `YYYY-MM-DD`. Use ISO 8601 — no slashes or other separators |
| `startDate` > `endDate` | `400`  | Date range is invalid — start must be ≤ end                               |

### Digital Account (Brazil)

| Scenario                      | Status | Cause                                               |
| ----------------------------- | ------ | --------------------------------------------------- |
| Invalid `transactionTypeName` | `400`  | Must be one of: `PIX`, `TED`, `BILL`, `TRANSACTION` |
| Invalid date format           | `400`  | Must be `YYYY-MM-DD`                                |
| `startDate` > `endDate`       | `400`  | Start date must be ≤ end date                       |

***

## Rate Limits

Requests are rate-limited per client certificate across all endpoints. Limits are applied separately to read (`GET`) and write (`POST`, `PATCH`, `DELETE`) operations — write endpoints have lower limits.

When you exceed the limit, the API returns `429 Too Many Requests`:

```json theme={null}
{ "message": "Too Many Requests" }
```

**Retry strategy:** Use exponential backoff with jitter. A safe starting point:

```python theme={null}
import time, random

def request_with_retry(fn, max_retries=4):
    for attempt in range(max_retries):
        response = fn()
        if response.status_code != 429:
            return response
        wait = (2 ** attempt) + random.uniform(0, 1)
        time.sleep(wait)
    raise Exception("Rate limit exceeded after retries")
```

For sustained high-volume use cases, contact your Clara integration team to discuss limit increases.

***

## Retry Guidance

| Status | Retry?              | Notes                                           |
| ------ | ------------------- | ----------------------------------------------- |
| `400`  | No                  | Fix the request first                           |
| `401`  | Yes — after refresh | Refresh token, then retry once                  |
| `403`  | No                  | Permission issue — retrying won't help          |
| `404`  | No                  | Resource doesn't exist                          |
| `429`  | Yes — with backoff  | Wait before retrying                            |
| `500`  | Yes — once          | Retry after 2–5 seconds; escalate if persistent |
| `511`  | No                  | Certificate configuration issue                 |

***

## Support Contacts

If you encounter persistent errors not covered here:

| Country  | Integration Support                                                           |
| -------- | ----------------------------------------------------------------------------- |
| Mexico   | [integration.support.mx@clara.team](mailto:integration.support.mx@clara.team) |
| Brazil   | [integration.support.br@clara.team](mailto:integration.support.br@clara.team) |
| Colombia | [integration.support.co@clara.team](mailto:integration.support.co@clara.team) |