Errors¶
Branch on errorCode; log detailedMessage and explanations but never parse them, as their wording may change.
{
"timestamp": "2026-11-16T10:15:30.123Z",
"path": "/api/v1/payout/create",
"message": "Validation failed",
"detailedMessage": "An instance of PayoutCreateDto has failed the validation",
"errorCode": "REQUEST_VALIDATION_FAILED",
"explanations": ["amount must be a positive number"]
}
Some 404, 409 and 429 answers come without errorCode (only timestamp, path, message), for example an unknown route or a record not found. Treat a 404 the same in either shape.
errorCode |
HTTP | Meaning | What to do |
|---|---|---|---|
REQUEST_VALIDATION_FAILED |
400 | Invalid body or filter; a required payer field is missing; a country not allowed | Fix the request; explanations lists each failed rule |
PAYMENT_OPERATION_FAILED |
400 | The provider refused, or the operation is not supported for this method or configuration | Do not retry unchanged; show detailedMessage to operators |
ACCESS_DENIED |
403 | Authentication, IP, licence or key-type failure, or a record of another merchant | See Authentication → When authentication fails |
NOT_FOUND |
404 | The record does not exist, or your provider binding lacks the needed setup | Check the id; for missing setup, contact Payard |
CONFLICT |
409 | The idempotencyKey is already used by another merchant |
Generate a new key for a new operation |
PAYIN_ACCOUNT_ON_COOLDOWN |
409 | Every payin account this payer may use is cooling down | Retry after the time in explanations |
RETRY_WITH |
449 | The transaction moved to another provider | Repeat the same request |
INTERNAL_SERVER_ERROR |
500 | An unexpected failure | Read detailedMessage before retrying |
Retrying a 500. Read detailedMessage first. Retry only with backoff and, for creates, always with the same idempotencyKey.
Timeouts on creates. A timeout does not mean nothing was created. Resend with the same idempotencyKey, or search by it (POST /payout/get-all with idempotencyKeys) before deciding the operation failed.
The request body is limited to 100 KB of JSON.