Getting started
Errors & rate limits
Error response format, error codes, validation issues, rate limits and retry guidance.
On this page
CentraPoint uses conventional HTTP status codes. 2xx means success, 4xx means the request needs to change, and 5xx means something went wrong on our side.
Error format#
Every API error response has a JSON body with a stable, machine-readable code and a human-readable message:
{
"error": "unauthorized",
"message": "Invalid API key"
}- Branch on
error(and the HTTP status). It is one of the codes below. - Show or log
message, but do not parse it: wording can change. - Validation failures add an
issuesarray.
Error codes#
| HTTP | error | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request | The body is not valid JSON (message: Body must be JSON), failed validation (issues included), or broke a business rule, e.g. Customer not found or Invoice is paid. The message is always safe to show. | Fix the request. Do not retry unchanged. |
| 401 | unauthorized | API key missing, malformed, unknown or revoked. | Check the Authorization header and key. |
| 403 | plan_restricted | Your plan does not include the API, or the feature (e.g. payment links). | Upgrade the plan in Settings → Billing. |
| 403 | plan_limit | A plan quota was reached (e.g. the customer or mandate limit), or an operation needs a plan feature you don't have (e.g. an invoice-collected subscription without Invoicing). | Upgrade, or reuse existing customers. |
| 403 | account_restricted | The account is read-only (suspended, cancelled or trial ended). Write requests only. | Resolve billing in the dashboard. |
| 403 | compliance_required | Your business verification is not approved yet, so the request would start a live payment (payment link or invoice pay link with only live gateways, EFT order on a live EFT gateway, checkout session, subscription on a live gateway, debit order mandate). Sandbox gateways keep working. See Business verification. | Complete Settings → Compliance, or use a sandbox gateway while you wait. |
| 404 | not_found | The resource does not exist in your organisation. | Check the ID or reference. |
| 409 | idempotency_conflict | The Idempotency-Key was already used with a different request body. | Use a new key for a new operation; resend the identical body when retrying. |
| 409 | invalid_state | The action isn't allowed from the resource's current status, e.g. resuming a cancelled subscription. With a Retry-After header, another request was changing the same resource at the same time (a subscription being replaced): nothing is stored under your Idempotency-Key. | Fetch the resource and check its status. With Retry-After: wait that many seconds, then send the same request again. |
| 409 | unsupported | The operation isn't supported for this resource, e.g. cancelling a subscription on a gateway that can't cancel through CentraPoint. | Do it in the gateway's portal. |
| 409 | invoice_linked | The subscription was started by a recurring payment link for an invoice: every payment is invoiced with that invoice's lines, so its amount cannot change (/api/v1/subscriptions/{id}/update or /retry). | Cancel it and create a recurring link for a new invoice with the new amount. |
| 409 | nothing_to_retry | Retry (POST /api/v1/subscriptions/{id}/retry) when no missed charge is left to re-collect (each was re-collected, or its charged retry is still pending) and you sent no amount, or on an invoice-linked subscription with no missed charge left to re-collect (with or without amount). A subscription that is not invoice-linked and never missed a charge is collected now instead. | Check the subscription's charges; wait for a pending retry's result. |
| 409 | external_subscription | The customer subscription is billed by your platform (collectionMethod: external, mirror mode): CentraPoint only records it, so it cannot pause, resume, retry, credit or discount it, add one-time or metered items, move its billing dates, change or remove its externalReference or change it from the customer portal. | Make the change on your platform, then record it with sync-period, change-plan or cancel. |
| 409 | not_external | POST /api/v1/customer-subscriptions/{id}/sync-period on a subscription CentraPoint bills itself. | Only send it for subscriptions you imported with collectionMethod external. |
| 409 | external_reference_conflict | POST /api/v1/customer-subscriptions with an externalReference that belongs to another kind of subscription (an external mirror record versus one CentraPoint bills) or to another customer's subscription. A 200 there would mirror a subscription CentraPoint bills, or hand back a mirror that nobody bills. | Check the existing subscription (GET /api/v1/customer-subscriptions?externalReference=); give a new subscription its own externalReference. |
| 409 | external_imports_unavailable | POST /api/v1/customer-subscriptions with collectionMethod: external (also a dry run) for a short time while CentraPoint is being updated (GET /api/v1/me then says capabilities.externalSubscriptions: false). Nothing was written. The response has a Retry-After header and is not stored under your Idempotency-Key. | Wait Retry-After seconds (or until capabilities.externalSubscriptions is true), then send the same request again. Reuse the same Idempotency-Key: the retry is processed, not answered from a stored refusal. |
| 409 | stale_period | POST /api/v1/customer-subscriptions/{id}/sync-period with a period that starts and ends before the recorded one and the same status: an older update that arrived late (for example a retry). Nothing changed. | Ignore it when the recorded period is newer; to correct the current period keep its start, or send the status that changed. |
| 409 | concurrent_update | POST /api/v1/customer-subscriptions/{id}/sync-period while other updates of the subscription kept winning (for example several syncs or a cancel at the same time). Nothing changed. The response has a Retry-After header and is not stored under your Idempotency-Key. | Wait Retry-After seconds, then send the same request again. The same Idempotency-Key is fine. |
| 409 | plan_code_taken | A plan with that code already exists in your organisation. | Look it up with GET /api/v1/plans?code= and reuse it. |
| 409 | already_allocated | The payment is already allocated to another invoice (POST /api/v1/invoices/{id}/payments with transactionReference). | Check the transaction's invoice; allocate another payment. |
| 409 | portal_disabled | The customer portal is off or not in your plan (POST /api/v1/customers/{id}/portal-link). | Enable it under Settings → Customer portal. |
| 422 | customer_inactive | A portal sign-in link was requested (email: false) for an inactive customer. | Reactivate the customer first. |
| 422 | not_sent | A portal link could not be emailed (inactive customer, template disabled, mail failure); url is included when known. | Fix the cause, or share the url another way. |
| 413 | invalid_request | Request body larger than 100 000 characters. | Send less data. |
| 429 | rate_limited | More than 120 requests in a minute with this API key (or 600 from one IP address). | Wait for Retry-After seconds, then retry. |
| 500 | internal_error | Unexpected server error. The message is generic; details are logged by CentraPoint. The body also has a reference (for example ERR-7K2M9Q): quote it when you contact support. | Retry with backoff (see below). Contact support if it persists. |
| 502 | gateway_error | A payment gateway rejected or failed an operation CentraPoint forwarded (subscription cancel). Nothing changed. | Retry later. |
| 502–504 | – | Proxy or network error before the request reached the API. The body may not be JSON. | Retry with backoff. |
Validation errors#
When the request body fails validation, the response is 400 with error: "invalid_request", message: "Invalid body", and one entry in issues per problem. Each issue has a code, a path to the field and a message; some codes include extra detail such as minimum or format. When a check runs after merging your fields with the stored record (for example a coupon PATCH), the response has the same shape, but message is the first issue (field path and message) instead of Invalid body.
{
"error": "invalid_request",
"message": "Invalid body",
"issues": [
{
"origin": "number",
"code": "too_small",
"minimum": 0,
"inclusive": false,
"path": ["amount"],
"message": "Too small: expected number to be >0"
},
{
"origin": "string",
"code": "invalid_format",
"format": "email",
"path": ["customerEmail"],
"message": "Invalid email address"
}
]
}Common mistakes#
- Sending
amountas a string ("499.00"). It must be a JSON number (499.00). - Sending
expiresAtwithout seconds or timezone (2026-10-31T23:59). Include both, e.g.2026-10-31T23:59:59+02:00. It must also be in the future and at most 1 year ahead. - Using a
currencynone of your enabled gateways accepts. Enable a suitable gateway first, or use a supported currency. - Sending invalid JSON. You get
400with the message Body must be JSON (noissues). An empty body is treated as{}, so required fields are reported as missing.
Rate limits#
Each API key may make 120 requests per minute, counted in fixed 60-second windows that start on the minute. The limit applies to the key as a whole, however your requests are routed.
Separately, a coarse guard allows 600 requests per minute per client IP address before the API key is even checked. It only protects against floods (for example many requests with bad keys); normal integrations never reach it. Setting an X-Forwarded-For header yourself does not change the client IP that is counted.
Rate-limit headers#
Every response to an authenticated request (success or error) includes the state of your key's current window:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Requests allowed per window (120). |
X-RateLimit-Remaining | Requests left in the current window. |
X-RateLimit-Reset | Unix time (seconds) when the current window ends and the count resets. |
Retry-After | Seconds to wait before retrying: on 429, and on a 409 that may succeed unchanged later (external_imports_unavailable, concurrent_update, invalid_state while another request changes the same resource). |
401 unauthorized responses carry no rate-limit headers, because the key is not known yet.
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1790323260
Retry-After: 17
{"error":"rate_limited","message":"Rate limit of 120 requests per minute exceeded for this API key"}If the per-IP guard is hit instead, the message is Too many requests from this network and the headers describe the IP window (limit 600).
Retries and timeouts#
- 429: wait for the number of seconds in
Retry-After(or untilX-RateLimit-Reset), then retry. - 500 internal_error, 502–504 and network errors: retry reads (
GET) with exponential backoff and jitter, e.g. 1s, 2s, 4s, up to about 5 attempts. - POST requests: send an
Idempotency-Keyand reuse it on retries, so a timeout or500never creates a second link, invoice or payment. See Idempotency, metadata & references for how to handle this safely. - 409 with a Retry-After header (
external_imports_unavailable,concurrent_update, andinvalid_statewhile another request changes the same resource): nothing changed. WaitRetry-Afterseconds, then send the same request again, with the same Idempotency-Key. These responses are never stored under the key, so the retry is processed. - Other 4xx: do not retry without changing the request.
- Use a client timeout of around 30 seconds.
Example: GET with retries#
async function getWithRetry(url, attempts = 5) {
for (let i = 0; i < attempts; i++) {
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.CENTRAPOINT_API_KEY}` },
signal: AbortSignal.timeout(30_000),
}).catch(() => null); // network error or timeout
if (res && res.status !== 429 && res.status < 500) return res; // success or non-retryable 4xx
let waitMs = Math.min(30_000, 1000 * 2 ** i) + Math.random() * 250; // backoff + jitter
if (res?.status === 429) {
const retryAfter = Number(res.headers.get("Retry-After"));
const reset = Number(res.headers.get("X-RateLimit-Reset"));
waitMs = retryAfter > 0 ? retryAfter * 1000 : reset > 0 ? reset * 1000 - Date.now() : waitMs;
}
await new Promise((r) => setTimeout(r, Math.max(0, waitMs)));
}
throw new Error("CentraPoint API unavailable after retries");
}