Skip to main content
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:
Error response shape

​
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.
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:
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 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:

​
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.