API errors

An overview of all the API errors you might encounter on the client and server side.

Overview

The Okra API uses standard HTTP response codes for success and failure notifications. In general:

  • 2xx codes indicate success,
  • 4xx codes indicate developer or user-related failures,
  • 5xx codes indicate Okra-related issues.
APISINGLE_LINK
SOCKET_IDUSSD
SLASUSPENDED
RATE_LIMITFLAGGED_USER
ENVEMPTY_QUEUE
QUEUE_FAILEDMAX_RETRY
DUPLICATED_QUEUEFAILED_QUEUE
PLANSELECTOR
EXPIREDCUSTOM
KILLNO_RECORD_ID

Breakdown of an Okra error

NameDescription
statusThe HTTP status code associated with the error. This will only be returned in the response body when the error information is provided via a webhook.
messageA user-friendly representation of the error code. null if the error is not related to user action.
This may change over time and is not safe for programmatic use.
dataResponse data from the API, including the details of the successful or failed response.
methodThe method that performs the error function
codeThe particular error code
typeA broad categorization of the error. Safe for programmatic use. Possible values: SUSPENDED, EMPTY_QUEUE, FLAGGED_USER, NO_RECORD_ID, RATE_LIMIT

API errors

Error CodeDescription
404The API Route you're using doesn't exist. Check our documentation and confirm the route.
400The API call failed. Please check the message payload.
429Too many requests. You can try again in 60 seconds. Check out more on Rate Limits
503Returned whenever a request takes more than 1 minute to complete.
5XXSomething went wrong on our side.

The 503 timeout error is returned by these endpoints:

  • /bvn-verify

  • /customer-verify

  • /nuban-verify

  • /nuban-name-verify

Some identity verification processes that time out eventually finish successfully. We strongly recommend that you implement an automatic retry for your requests to these endpoints. Add a short delay to your automatic retries to ensure that you handle 503 timeout errors successfully.

503 error response

{
  "status": "error",
  "message": "Our data source has returned a timeout response. Please retry the request. "
}

Was this page helpful?

On this page