Skip to content

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.