Errors

Every failure is JSON in the same envelope, including a 500. Branch on code, show the message, and log the request_id.

The envelope

{
"error": {
  "type": "invalid_request_error",
  "code": "parameter_invalid",
  "message": "Metered prices must use interval='month'.",
  "param": "usage_type",
  "request_id": "9f4c2b1ad7e84c0fa1b3e6d590c72b48"
}
}

This shape holds for everything, including unhandled server errors, schema validation failures and requests to a path that does not exist (404 route_not_found) or with a method the path does not serve (405 method_not_allowed, with an Allow header). Your parser never needs a fallback path for a plain-text body.

Log the request id

Every response carries X-Request-Id, and every error repeats it in the body. It is the join key into BillKit’s own logs. A support conversation that starts with a request id is a short one; one that starts with “a payment failed this morning” is not.

If you send your own X-Request-Id it is echoed back, provided it is 8 to 128 characters of letters, digits, _, ., : or -. Anything else is replaced with a generated id, because the value ends up in logs and an unvalidated one would let a caller forge log lines.

Status codes

Card declines on checkouts and renewals never surface as an error on your API call, because the charge happens at Mollie after the customer leaves your server. A decline arrives as payment.failed, subscription.past_due or checkout.session.expired over webhooks. The calls that move money synchronously are the exception: a plan change’s proration charge, the payment of a past-due period through reauthorize_payment_method, and a refund answer 402 payment_refused (type: payment_error, reason: payment_refused) when Mollie refuses to create the payment or refund, and nothing moves. The other 402 is tenant_suspended, about your own BillKit account.

Codes

Reason codes

code answers “what kind of failure”; many distinct situations share one. reason is the i18n-stable supplement for the cases where a user-facing surface has to say something specific. Map reason to your own copy, and fall back to code when you do not recognise it. New reasons can be added at any time, which is safe precisely because unknown ones fall back.

Retrying

429, every 5xx except 501, 409 idempotency_in_progress and 409 operation_pending are worth retrying. A 501 is a permanent answer about this deployment, and every other 4xx will fail identically however many times you send it.

Use exponential backoff with jitter, and send the same Idempotency-Key on every attempt. A retryable response clears the stored key, so the retry does the work; a success or any other client error replays the original response. Either way you cannot double-charge by retrying.

503: read reason before assuming nothing happened

A 500 tells you a request failed somewhere in the middle. Retrying with the same Idempotency-Key runs it again, and the money paths are built so that a repeat cannot charge or refund twice. A 503 service_unavailable comes in two kinds, told apart by reason:

• not_attempted: we were at our capacity ceiling and refused the request before running it, so nothing was attempted.
• outcome_unknown: the request started and was cut off before it finished (it waited too long for a lock or a query, or lost its database connection). Its own database writes were undone, but a payment it had already asked the provider for may exist. Treat it like a 500: retry with the same Idempotency-Key. The retry runs the request again rather than replaying a stored answer.

It carries Retry-After: 1. The official SDKs ignore it in favour of their own jittered backoff, because a fixed delay synchronises every shed client into one retry, which is the stampede that caused the shedding. Honour it if you are writing your own client and have no backoff of your own; prefer jitter if you do.

Always send the same Idempotency-Key. For outcome_unknown it is what stops a retry from charging twice; for not_attempted it still matters, because the retry may race a different attempt that did run.