Error Handling

​

Error model

{
  "statusCode": 400,
  "message": "Invalid request payload",
  "data": null,
  "errors": [
    {
      "field": "beneficiary.accountNumber",
      "message": "Account number is required"
    }
  ]
}

​

HTTP status codes

​

Retry strategy

• Use idempotency keys (e.g., payoutRef) when retrying POST requests to avoid double submissions.
• Retry 5xx and 429 responses with exponential backoff (e.g., 1s, 2s, 4s) up to a maximum time window.
• Avoid retrying validation (4xx) errors unless the payload is corrected.

​

Monitoring and alerting

• Log the statusCode, message, and any nested errors for observability.
• Set alerts on elevated 5xx or 429 error rates per endpoint.
• Subscribe to status.useyala.com for incident notifications.

​

Getting help

• Request ID or payoutRef
• Timestamp (UTC)
• Endpoint and HTTP method
• Full response payload and headers