> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleo-pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Cleo Pay API Error Codes and Troubleshooting
> Reference for Cleo Pay API HTTP error codes. Understand what each status code means and how to handle errors in your integration.
The Cleo Pay API uses standard HTTP status codes to communicate success or failure. All error responses include a JSON body with a machine-readable `error` code and a human-readable `message` to help you diagnose the issue.
A typical error response looks like this:
```json title="Error response shape" theme={null}
{
"error": "INVALID_REQUEST",
"message": "amountCents must be at least 1"
}
```
***
## HTTP status code reference
**What it means:** The request body is malformed, contains invalid field types, is missing a required field, or contains a logically invalid combination of fields.
**Common causes:**
* Missing a required field (e.g., omitting `bankAccountId` on a payment request).
* Sending both `contactId` and `payableId` in the same `POST /v1/payments` request — these fields are mutually exclusive.
* Sending malformed JSON (e.g., unquoted string values, trailing commas).
**How to fix:** Read the `message` field in the error response — it will identify the specific field or conflict. Double-check your request body against the [API spec](/reference).
**What it means:** The request did not include a valid Bearer token, or the token is expired or malformed.
**Common causes:**
* Forgetting to include the `Authorization` header entirely.
* Passing the token without the `Bearer ` prefix (e.g., sending only the raw token string).
* Using an expired token.
**How to fix:** Ensure every request includes the header:
```bash theme={null}
Authorization: Bearer
```
If your token has expired, obtain a new one from your authentication provider and retry.
**What it means:** Your token is valid and authenticated, but your account or role does not have permission to perform the requested action.
**Common causes:**
* Attempting to access a resource that belongs to a different organization.
* Trying to use a feature (e.g., `NEXT_AVAILABLE` clearing) that has not been enabled for your account.
**How to fix:** Verify that the resource ID in the request belongs to your organization. If you believe you should have access, contact your Cleo Pay account manager.
**What it means:** The resource you referenced does not exist, or your account does not have access to it. Cleo Pay returns 404 (rather than 403) for resources you cannot access, to avoid leaking information about resource existence.
**Common causes:**
* Typo in a resource ID (e.g., `payable_01hwxyz123` vs. `payable_01hwxyz124`).
* Referencing a resource that was deleted or belongs to another organization.
**How to fix:** Double-check the resource ID. List the relevant resources (e.g., `GET /v1/contacts`) to confirm the ID is correct and accessible.
**What it means:** The request conflicts with the current state of a resource. The most common cause is duplicate detection.
**Common causes:**
* Creating a contact that shares a name or email with an existing contact, without setting `allowDuplicates: true`.
**How to fix:** If the duplicate is intentional, resend the request with `"allowDuplicates": true` in the request body. Otherwise, retrieve the existing contact and update it instead of creating a new one.
**What it means:** The request is well-formed and authenticated, but the data is semantically invalid — it fails a business rule.
**Common causes:**
* `amountCents` is less than `1` (minimum payment is 1 cent).
* `scheduledAt` is today's date or in the past.
* `totalAmountCents` on a payable is less than `1`.
* A field value is outside its allowed range or format.
**How to fix:** Read the `message` field carefully. It will describe the specific rule that was violated (e.g., `"scheduledAt must be a future date"`).
**What it means:** You have exceeded the API rate limit.
**Common causes:**
* Sending too many requests in a short window (e.g., unbounded parallel requests without throttling).
**How to fix:** Back off and retry after a delay. Implement exponential backoff in your integration. Check the `Retry-After` response header if present — it indicates how many seconds to wait before retrying.
**What it means:** An unexpected error occurred on the Cleo Pay server. This is not caused by your request.
**How to fix:** Retry the request after a short delay. If the issue persists, contact [Cleo Pay support](mailto:support@cleo-pay.com) and provide the request ID from the response headers if available.
***
## Common integration mistakes
The following mistakes account for the majority of errors seen in new integrations:
| Mistake | Resulting error |
| --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Forgetting the `Authorization` header | `401 Unauthorized` |
| Sending `contactId` AND `payableId` in the same payment request | `400 Bad Request` |
| Setting `amountCents` to `0` or a negative value | `422 Unprocessable Entity` |
| Setting `scheduledAt` to today's date or a past date | `422 Unprocessable Entity` |
| Exceeding 3 micro-deposit verification attempts | Account status becomes `unverified` (no HTTP error on the attempt itself, but subsequent attempts are rejected) |
| Creating a duplicate contact without `allowDuplicates: true` | `409 Conflict` |
| Using a raw token string without the `Bearer ` prefix | `401 Unauthorized` |
***
## Debugging tips
* **Always read the `message` field.** Cleo Pay error responses include a human-readable description that directly identifies the problem.
* **Log request IDs.** Include request/response logging in your integration so you can correlate errors with specific API calls.
* **Use the staging environment** (`https://api.cleo-pay.com`) for development and testing to avoid affecting production data.