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

# Error Handling

> Error response format, error codes, and troubleshooting tips

## Error response format

All errors return this structure:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "payment_amount must be a positive integer (cents)",
    "field": "payment_amount",
    "request_id": "4e9024e3-125d-4d08-a392-4fa34f6bda44"
  }
}
```

| Property     | Always present | Description                                                                                                              |
| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `code`       | Yes            | Machine-readable error code                                                                                              |
| `message`    | Yes            | Human-readable description                                                                                               |
| `field`      | No             | Dot-notation path to the problematic field (e.g., `address.state`). Only present when a specific field caused the error. |
| `request_id` | Yes            | Unique UUID for this request. Include in support tickets.                                                                |

## Error codes

| Code                   | HTTP Status | Description                                                                    |
| ---------------------- | ----------- | ------------------------------------------------------------------------------ |
| `VALIDATION_ERROR`     | 400         | Invalid request body or query parameters                                       |
| `AUTHENTICATION_ERROR` | 401         | Missing, malformed, or invalid API key                                         |
| `AUTHORIZATION_ERROR`  | 403         | Valid key but not permitted (e.g., suspended account, disallowed payment type) |
| `NOT_FOUND`            | 404         | Resource not found or belongs to a different partner                           |
| `CONFLICT`             | 409         | Duplicate resource (same email, external\_id, or billing period)               |
| `RATE_LIMITED`         | 429         | Too many requests                                                              |
| `INTERNAL_ERROR`       | 500         | Unexpected server error                                                        |

## Example error responses

<AccordionGroup>
  <Accordion title="400 — Validation Error">
    ```json theme={null}
    {
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Must be YYYY-MM-DD",
        "field": "date_of_birth",
        "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
    ```
  </Accordion>

  <Accordion title="401 — Authentication Error">
    ```json theme={null}
    {
      "error": {
        "code": "AUTHENTICATION_ERROR",
        "message": "Missing x-api-key header",
        "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
    ```
  </Accordion>

  <Accordion title="404 — Not Found">
    ```json theme={null}
    {
      "error": {
        "code": "NOT_FOUND",
        "message": "Consumer not found",
        "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
    ```
  </Accordion>

  <Accordion title="409 — Conflict">
    ```json theme={null}
    {
      "error": {
        "code": "CONFLICT",
        "message": "A consumer with this email or external_id already exists for this partner",
        "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Tips

* Always check for the `error` key in the response before processing data.
* Use `field` for field-level error highlighting in your UI.
* Include `request_id` when contacting support.