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 resourceContact 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 [email protected] for expedited assistance.