Errors

Olympus Pay uses standard HTTP status codes. Error bodies are JSON.

{
  "error": "This API key does not have the payouts:create scope.",
  "code": "permission_denied",
  "request_id": "req_4f9c2b7e1a8d40c39b6e2f1a"
}

Field	Meaning
`error`	A message for a person. For invalid input it is an object: `{ "formErrors": [], "fieldErrors": { "amount": ["Number must be greater than or equal to 0.01"] } }`. Do not parse it.
`code`	A stable identifier to branch on in code
`request_id`	Also sent as the `X-Request-Id` header. Give it to support.

Errors never contain internal detail, stack traces or database messages.

Codes#

Status	`code`	Meaning	What to do
`400`	`invalid_request`	Invalid input, a business rule was not met (sandbox key on payouts, insufficient balance, refund larger than what remains)	Fix the request. Do not retry unchanged.
`401`	`authentication_failed`	Bad, missing, revoked or expired key, or IP not allowed	Check the key. See Authentication.
`403`	`permission_denied`	Missing scope, business not verified, or `bankDetails` do not match the saved account	Add the scope, finish verification, or fix the destination.
`404`	`not_found`	No such object for your business	Check the id and the environment (sandbox versus live).
`409`	`conflict`	The object changed underneath you, for example a concurrent refund	Read the object again and decide.
`413`	`payload_too_large`	Body too large	Send less.
`429`	`rate_limited`	Too many requests	Wait for `Retry-After`, then retry with backoff.
`500`	`internal_error`	Something went wrong on our side	Retry with backoff. Report the `request_id` if it persists.
`501`	`not_implemented`	Not available for that currency or path yet	Do not retry.
`502`	`internal_error`	The payment provider failed or could not be reached	Retry with backoff, after checking whether the operation took effect.
`503`	`unavailable`	Temporarily unavailable	Retry with backoff.

A 202 is not an error: the operation is waiting for a second person in your business to approve it.

Branch on code and the HTTP status, never on the text of error.
Log request_id with every failure.
For 5xx on anything that moves money, first check whether it worked (GET /payouts, GET /payments/{id}) or use an idempotency key, then retry.