Centsless returns standard HTTP status codes on every response. When a request fails, the response body is a JSON object with two fields: error, a machine-readable code you can match against in your integration, and message, a human-readable description suitable for logging.
Error response structure
Every error response follows this schema:
{
"error": "ERROR_CODE",
"message": "Human-readable description"
}
HTTP status codes
| Status | Meaning |
|---|
200 OK | Request succeeded. |
201 Created | Resource created successfully (for example, a new API key). |
400 Bad Request | Validation error — a required field is missing or a field value is not a valid enum option. |
401 Unauthorized | The x-api-key header is missing or the key is invalid. |
403 Forbidden | The API key is valid but lacks permission for the requested endpoint. |
404 Not Found | The requested transaction or resource does not exist. |
429 Too Many Requests | You have exceeded the rate limit for your API key (1,000 req/hr sandbox, 10,000 req/hr production). |
500 Internal Server Error | An unexpected error occurred on the server. Retry with exponential backoff. |
Common error codes
UNAUTHORIZED — 401
Returned when the x-api-key header is absent or the key has been revoked.
{
"error": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
FORBIDDEN — 403
Returned when your key is valid but is not scoped for the endpoint you called. For example, a merchant key calling an admin-only endpoint.
{
"error": "FORBIDDEN",
"message": "Insufficient permissions for this endpoint"
}
VALIDATION_ERROR — 400
Returned when a required field is missing from the request body or a field value falls outside the allowed enum.
{
"error": "VALIDATION_ERROR",
"message": "merchant_id is required"
}
NOT_FOUND — 404
Returned when you reference a transaction ID or other resource that does not exist.
{
"error": "NOT_FOUND",
"message": "Transaction not found"
}
The compliance_status field in transaction responses (PASS, WARN, or FAIL) signals jurisdiction compliance issues. These are separate from HTTP errors — a transaction can return 200 OK with a compliance_status of WARN or FAIL. Check this field in every transaction response alongside the HTTP status.