Skip to main content

​
Error model

All error responses follow a consistent envelope: 
{
  "statusCode": 400,
  "message": "Invalid request payload",
  "data": null,
  "errors": [
    {
      "field": "beneficiary.accountNumber",
      "message": "Account number is required"
    }
  ]
}
Some legacy endpoints may omit the errors array. Always check the message field as a fallback.

​
HTTP status codes

CodeMeaningTypical causeRecommended action
400Validation failureMissing or malformed fieldsFix the payload and retry.
401UnauthorizedIncorrect or missing x-api-keyRefresh credentials or regenerate keys.
403ForbiddenTenant not permitted to access the resource, or a newly generated API key is still propagatingIf the key was just created, wait up to 20-30 minutes and retry. Otherwise contact Yala support to adjust permissions.
404Not foundResource removed or incorrect identifierConfirm the ID and try again.
409ConflictDuplicate payout reference or business constraintGenerate a new idempotency reference.
422UnprocessableBusiness rule violation (e.g., beneficiary not approved)Surface the message to internal ops for review.
429Rate limitedToo many requests in a short windowBack off exponentially and retry with jitter.
500Internal errorPlatform issueRetry with backoff and report to support if persistent.

​
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

Collect the following details before reaching out to support:
  • Request ID or payoutRef
  • Timestamp (UTC)
  • Endpoint and HTTP method
  • Full response payload and headers
Email these details to developers@useyala.com for expedited assistance.