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

# Errors

> Standard error format (RFC 7807) and common codes.

Every error response from the Cativa API follows the **same format**, based on the [RFC 7807 Problem Details](https://www.rfc-editor.org/rfc/rfc7807) standard. This page describes that format and the HTTP codes you can encounter.

## Standard error shape

```json theme={null}
{
  "type": "Validation.Email.Invalid",
  "status": 400,
  "title": "Validation Error",
  "detail": "The request failed validation.",
  "traceId": "0HMV5JK6L6NPL:00000003"
}
```

| Field     | Type   | Description                                                                                         |
| --------- | ------ | --------------------------------------------------------------------------------------------------- |
| `type`    | string | Stable error type identifier. Use to branch logic on your side.                                     |
| `status`  | number | HTTP code echoed in the body (RFC 7807 compatibility).                                              |
| `title`   | string | Short error category (`Validation Error`, `Not Found`, `Forbidden`, `Internal Server Error`, etc.). |
| `detail`  | string | English message describing the problem. **Don't display directly to end users.**                    |
| `traceId` | string | Correlation id for debugging. **Include in any support ticket.**                                    |

For validation responses, an additional `errors` field may be populated with per-field errors in the format `Dictionary<string, ProblemDetailsFieldError[]>`.

## Common HTTP codes

| Status            | Title                                  | What it means                                                                          | What to do                                                            |
| ----------------- | -------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `400`             | `Validation Error` or `Business Error` | Body invalid in format (malformed JSON, wrong content-type) or business rule violated. | Fix the request before retrying.                                      |
| `401`             | —                                      | Missing, invalid or expired token.                                                     | Renew/generate a new credential. **Don't retry** without action.      |
| `403`             | `Forbidden`                            | Token is valid but lacks permission for the operation.                                 | Check API Key or OAuth scope.                                         |
| `404`             | `Not Found`                            | Resource doesn't exist.                                                                | Confirm `id`.                                                         |
| `422`             | `Unprocessable Entity`                 | Body well-formed but entity invalid (domain rules).                                    | Read `detail` and adjust.                                             |
| `500`             | `Internal Server Error`                | Cativa-side error.                                                                     | Retry with backoff. If it persists, open a ticket with the `traceId`. |
| `502`/`503`/`504` | —                                      | Transient unavailability.                                                              | Retry with exponential backoff.                                       |

### Example `400 Validation Error`

```json theme={null}
{
  "type": "Validation.User.Email.Required",
  "status": 400,
  "title": "Validation Error",
  "detail": "Email is required.",
  "traceId": "0HMV5JK6L6NPL:00000003"
}
```

## Anti-pattern: ignoring `traceId` in logs

<Warning>
  Always log `traceId` together with any API error you catch. Without it, the Cativa support team **cannot investigate** your case — it's like asking for help without saying what error happened. Include `traceId`, HTTP status and `type` in your logger from day one.
</Warning>

## How to report an error

When opening a ticket at [dev@cativa.digital](mailto:dev@cativa.digital), always include:

1. The `traceId` returned in the error response body.
2. The `type` and the `status` of the error.
3. A sample of the request (URL, method, relevant headers — don't expose the full key).
4. Approximate time (with timezone) when the error happened.

Those details let the team correlate with internal logs quickly.

## Next steps

<CardGroup cols={2}>
  <Card title="Identity and Users" icon="user" href="/en/concepts/identity-and-users">
    Where you'll see `400 Validation Error` (invalid field) most often.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/en/concepts/webhooks">
    How `X-Cativa-Execution-Id` helps you deduplicate redelivered webhooks.
  </Card>
</CardGroup>