# Errors

> HTTP status codes, the error body, and what to do about each one.

Camel uses standard HTTP status codes. `2xx` means the request worked, `4xx` means something in the request needs fixing, and `5xx` means a provider or Camel couldn't complete it.

## Error body

Errors return a JSON body with a `detail` message:

**409 Conflict**

```json
{
  "detail": "Refund amount exceeds the unreserved payment balance"
}
```

Validation errors (`422`) list each invalid field instead:

**422 Unprocessable Content**

```json
{
  "detail": [
    {
      "type": "greater_than",
      "loc": ["body", "amount"],
      "msg": "Input should be greater than 0",
      "input": 0
    }
  ]
}
```

## Status codes

| Status | Meaning |
| --- | --- |
| `200` `201` | Success. |
| `202` | The provider's answer is uncertain. The resource has status `unknown` and Camel will settle it. See [Idempotency](https://camelpayment.com/docs/idempotency.md). |
| `400` | A malformed header or cursor. |
| `401` | The API key is missing, malformed, or revoked. |
| `402` | Production only: your Camel invoice is past due. Pay it from Billing. |
| `404` | The resource doesn't exist in this key's environment. |
| `409` | The request conflicts with the resource's state (a refund larger than what's left) or with an idempotency key already in use. |
| `422` | The body is invalid, or the connection can't do what you asked. |
| `429` | Too many requests. See [Rate limits](https://camelpayment.com/docs/rate-limits.md). |
| `502` | The provider returned an error. The body is the resource, with status `failed`. |
| `503` | Exchange rates are temporarily unavailable. |

## Declined payments

A declined card is not an HTTP error. The request returns `201` and the payment has `status: "rejected"`. The provider's own status is in `provider_status`. When Camel couldn't reach a result, the payment carries a `failure` object:

**failure**

```json
{
  "failure": {
    "code": "unknown",
    "provider_code": null
  }
}
```

`failure.code` is one of `insufficient_funds`, `invalid_card`, `expired_card`, `security_code_invalid`, `fraud_suspected`, `authentication_required`, `invalid_credentials`, `provider_unavailable`, `rate_limited`, `duplicate_operation`, or `unknown`.

## Request ids

Every response has an `X-Request-ID` header. Include it when you contact support. You can also send your own `X-Request-ID` (8 to 64 letters, digits, `-` or `_`) and Camel will use it.
