Errors and troubleshooting

Understand failures and choose whether to retry, correct input, or request support.

Error envelope

Merchant errors return an HTTP error status and an error object.

{
  "error": {
    "code": "MERCHANT_INSUFFICIENT_FUNDS",
    "message": "Insufficient merchant funds or merchant-owned payout liquidity"
  }
}

Authentication middleware may include additional fields such as success. Use HTTP status and the error object; do not depend on an exact message string.

Status reference

HTTP status	Merchant code	Action
`400`	`MERCHANT_INVALID_REQUEST`	Correct the body or idempotency key
`401`	`AUTH_MISSING_API_KEY` or `AUTH_INVALID_API_KEY`	Check the API key and environment
`403`	`AUTH_INSUFFICIENT_SCOPE`	Use a key with the required scope
`403`	`MERCHANT_DISABLED`	Contact your administrator
`403`	`MERCHANT_APPROVAL_REQUIRED`	Resolve the approval requirement
`404`	`MERCHANT_NOT_FOUND`	Check the payment ID, merchant, and endpoint kind
`409`	`MERCHANT_CONFLICT`	Check for idempotency content mismatch or stale configuration
`409`	`MERCHANT_INVALID_STATE`	Read the current state before acting
`409`	`MERCHANT_INSUFFICIENT_FUNDS`	Check merchant funds and payout availability
`429`	`MERCHANT_LIMIT_EXCEEDED`	Respect Retry-After and check rate or business limits
`500`	`MERCHANT_INTERNAL`	Retry safely with the same idempotency key; escalate persistent failures

Network gateways can also return errors without a JSON body. Handle response parsing failures without treating them as payment failures.

Requests that reach merchant route processing receive X-Deripay-Request-ID and Cache-Control: no-store. Authentication failures or upstream errors may omit them. Keep payment responses out of shared caches.

429 MERCHANT_LIMIT_EXCEEDED currently includes Retry-After: 60, even for a daily or transaction limit. That header is not a promise that waiting 60 seconds will resolve every limit. See limits and input formats.

Common validation mistakes

Sending 100.50 instead of integer cents.
Sending cents that are not divisible by 100.
Omitting currency: "KES" or method: "stk" for collections.
Passing an unsupported phone number.
Using a reference longer than 80 UTF-8 bytes.
Reusing an idempotency key with a different body.
Sending unknown or duplicate JSON fields.

A route returns plain 404

Confirm the API base URL includes /api/v1. If every merchant endpoint returns plain 404, the merchant module may not be activated on that deployment. The presence of the web dashboard does not guarantee API activation.

A payout remains pending

queued, submitted, and unknown are not final failures. Keep the original payment ID and idempotency key. Poll with backoff or seek support rather than issuing a replacement payout.

Include the payment ID, endpoint, HTTP status, approximate request time, and X-Deripay-Request-ID response header when available. Never share API keys, merchant passwords, webhook secrets, or full customer details in an error report.

Error envelope

Merchant errors return an HTTP error status and an error object.

{
  "error": {
    "code": "MERCHANT_INSUFFICIENT_FUNDS",
    "message": "Insufficient merchant funds or merchant-owned payout liquidity"
  }
}

Authentication middleware may include additional fields such as success. Use HTTP status and the error object; do not depend on an exact message string.

Status reference

HTTP status	Merchant code	Action
`400`	`MERCHANT_INVALID_REQUEST`	Correct the body or idempotency key
`401`	`AUTH_MISSING_API_KEY` or `AUTH_INVALID_API_KEY`	Check the API key and environment
`403`	`AUTH_INSUFFICIENT_SCOPE`	Use a key with the required scope
`403`	`MERCHANT_DISABLED`	Contact your administrator
`403`	`MERCHANT_APPROVAL_REQUIRED`	Resolve the approval requirement
`404`	`MERCHANT_NOT_FOUND`	Check the payment ID, merchant, and endpoint kind
`409`	`MERCHANT_CONFLICT`	Check for idempotency content mismatch or stale configuration
`409`	`MERCHANT_INVALID_STATE`	Read the current state before acting
`409`	`MERCHANT_INSUFFICIENT_FUNDS`	Check merchant funds and payout availability
`429`	`MERCHANT_LIMIT_EXCEEDED`	Respect Retry-After and check rate or business limits
`500`	`MERCHANT_INTERNAL`	Retry safely with the same idempotency key; escalate persistent failures

Network gateways can also return errors without a JSON body. Handle response parsing failures without treating them as payment failures.

Common validation mistakes

Sending 100.50 instead of integer cents.
Sending cents that are not divisible by 100.
Omitting currency: "KES" or method: "stk" for collections.
Passing an unsupported phone number.
Using a reference longer than 80 UTF-8 bytes.
Reusing an idempotency key with a different body.
Sending unknown or duplicate JSON fields.

A route returns plain 404

A payout remains pending

queued, submitted, and unknown are not final failures. Keep the original payment ID and idempotency key. Poll with backoff or seek support rather than issuing a replacement payout.

Errors and troubleshooting

Error envelope

Status reference

Common validation mistakes

A route returns plain 404

A payout remains pending

On this page

Errors and troubleshooting

Error envelope

Status reference

Common validation mistakes

A route returns plain 404

A payout remains pending

On this page