Errors
Common shape of error responses.
JSON errors include statusCode, error (stable code), message, timestamp and path (the request path). A 409 with idempotency_request_in_progress means the same Idempotency-Key is still being processed: retry as is. A 422 idempotency_key_reuse means you reused the key with a different body.
Request bodies and responses use camelCase (orderReference, expiresInSeconds, beneficiaryId, settledAt, eventTypes). The ValidationPipe rejects undeclared fields (400) and does not convert names that differ from the contract.
An undeclared field or a field with an invalid type returns the standard validation 400: error is "Bad Request" and message is an array with one text per problem (e.g. "property order_reference should not exist"). In the nested verification objects, a key that is not camelCase returns 400 validation_failed with fields[].code = unknown_field.
On routes that take a UUID, an id in any other format returns 404 not_found, the same as a resource that does not exist or belongs to another merchant.
Routes in this reference are listed under collections, payouts, balance, verification and events.