Error handling

When a request can't be processed, the Centrobill API returns an HTTP status code and a JSON error object describing the reason.

Request errors vs payment outcomes

These are two different types of errors and should be handled separately.

Request errors occur when the request itself is invalid. For example, a missing field, invalid credentials, or a server-side issue. The HTTP status code reflects the problem directly.

Payment outcomes occur when the gateway accepts the request, but the payment is declined. A declined payment still returns 201 Created at the HTTP level. The outcome is indicated by payment.status and payment.code in the response body, not by the HTTP status code.

A payment.code of "0" with payment.status of "success" indicates approval. Any other payment.code value indicates a decline.

HTTP status codes and what to do

Code	Meaning	What to do
`200`	OK — retrieval or update succeeded	—
`201`	Created — operation succeeded	—
`400`	Bad Request — a required field is missing or invalid	Fix the request body and retry with a new `X-Request-ID`
`401`	Unauthorized — API key is missing or invalid	Check your key; do not retry until fixed
`403`	Forbidden — valid key but insufficient permissions, or IP not allowlisted	Contact support; do not retry
`404`	Not Found — the requested resource does not exist	Do not retry
`500`	Internal Server Error — gateway-side fault	Retry after a delay with the same `X-Request-ID`

Timeouts: if a request times out and no response is received, retry with the same X-Request-ID. If you're uncertain whether the charge went through, query the Feed API before retrying.

Payment declines: a declined payment still returns 201 Created at the HTTP level. To check whether a payment was approved, look at payment.code in the response body - 0 means approved, anything else is a decline. Check the decline code before deciding whether to retry. Some declines are permanent (for example, a stolen card) while others may succeed on retry.

For safe retry behaviour on timed-out requests, see Idempotency.

Error response body

When a 400 error occurs, the response body includes an errors object identifying the specific field or fields that caused the problem:

{
  "message": "Bad Request",
  "errors": {
    "parameterName": "Parameter is invalid or missing"
  }
}

Payment-level decline codes

Payment declines carry a payment.code value that identifies the specific reason. Two separate reference pages document the full set of codes:

Issuer decline codes & Merchant Advice Codes — codes returned by the card issuer
Gateway decline codes — codes returned by the Centrobill gateway