Errors and recovery | DeriPay Deriv Docs

Use error.code to decide how to handle a failed request. Errors have the following format:

{
  "success": false,
  "error": {
    "code": "PAYMENT_UNCONFIRMED",
    "message": "The payment outcome could not be confirmed. Read the existing operation; do not create a replacement."
  }
}

HTTP	Code	Handling
400	`INVALID_REQUEST`	Check field types, required fields and the current transaction status.
401	`AUTHENTICATION_REQUIRED`	Verify the key; reconnect the customer's Deriv authorization when required.
403	`ACCESS_DENIED`	Check workspace approval, scopes, country restrictions and ownership.
404	`NOT_FOUND`	Check IDs and the authenticated connection.
409	`OPERATION_CONFLICT`	Check the existing transaction or transfer; keep its key or UUID.
410	`EXPIRED`	Inspect the existing operation before restarting.
412	`ACCOUNT_NOT_ELIGIBLE`	Check account permissions, verification, limits and balance.
413	`REQUEST_TOO_LARGE`	Reduce the request body.
422	`PAYMENT_REJECTED`	Review account eligibility, amount and balance.
429	`RATE_LIMITED`	Wait; honor `Retry-After` when present.
500	`INTERNAL_ERROR`	Check the existing outcome before retrying.
502	`PAYMENT_UNCONFIRMED`	Outcome is unconfirmed; never create a replacement.
503	`SERVICE_UNAVAILABLE`	Wait, then retry with the same request and key or UUID.
504	`OUTCOME_UNKNOWN`	A timeout does not prove failure; read the existing operation.

Each endpoint lists the errors it can return. After an SSE stream opens, errors use this JSON structure in an error event; the HTTP status stays 200.

The transaction's failure field is null unless the payment failed or needs reconciliation. Failed payments use PAYMENT_FAILED; unresolved payments use PAYMENT_UNCONFIRMED. Reports can group processing problems under PAYMENT_PROCESSING_ISSUE. Check the transaction before retrying a payment.

When contacting support, include the transaction or transfer ID, connection ID, UTC timestamp, HTTP status and error code. Leave out API keys, access tokens, verification codes and PINs.

Use error.code to decide how to handle a failed request. Errors have the following format:

{
  "success": false,
  "error": {
    "code": "PAYMENT_UNCONFIRMED",
    "message": "The payment outcome could not be confirmed. Read the existing operation; do not create a replacement."
  }
}

HTTP	Code	Handling
400	`INVALID_REQUEST`	Check field types, required fields and the current transaction status.
401	`AUTHENTICATION_REQUIRED`	Verify the key; reconnect the customer's Deriv authorization when required.
403	`ACCESS_DENIED`	Check workspace approval, scopes, country restrictions and ownership.
404	`NOT_FOUND`	Check IDs and the authenticated connection.
409	`OPERATION_CONFLICT`	Check the existing transaction or transfer; keep its key or UUID.
410	`EXPIRED`	Inspect the existing operation before restarting.
412	`ACCOUNT_NOT_ELIGIBLE`	Check account permissions, verification, limits and balance.
413	`REQUEST_TOO_LARGE`	Reduce the request body.
422	`PAYMENT_REJECTED`	Review account eligibility, amount and balance.
429	`RATE_LIMITED`	Wait; honor `Retry-After` when present.
500	`INTERNAL_ERROR`	Check the existing outcome before retrying.
502	`PAYMENT_UNCONFIRMED`	Outcome is unconfirmed; never create a replacement.
503	`SERVICE_UNAVAILABLE`	Wait, then retry with the same request and key or UUID.
504	`OUTCOME_UNKNOWN`	A timeout does not prove failure; read the existing operation.

Each endpoint lists the errors it can return. After an SSE stream opens, errors use this JSON structure in an error event; the HTTP status stays 200.

When contacting support, include the transaction or transfer ID, connection ID, UTC timestamp, HTTP status and error code. Leave out API keys, access tokens, verification codes and PINs.