Bureau HTTP Status Codes

Check Status Codes to handle codes received from Bureau, build your business logic and take remedial action at your end.

To provide you with the best experience, we aim to successfully process all API calls. However, API calls can sometimes fail due to external factors and other unforeseen circumstances such as human error while providing inputs, network errors, and intermittent connectivity.

Bureau leverages HTTP status codes to communicate the success or failure of your API requests. This section details what these codes represent and how to handle them effectively.

Understanding Response Codes

2XX: Successful execution of your API request.
4XX (Client Errors): These indicate issues with the request, often due to incorrect data or missing information. The most common code used here is 400 (Bad Request).
5XX (Network and Server Errors): These indicate the rare occurrences there is a problem within Bureau's servers. Treat them as indeterminate errors.

Error Codes and Next Steps

The table below lists the error codes we return and the suggested steps to resolve the error.

HTTP Status Code	Message	Description	Next Steps
200	Success	The request was successfully processed and the response was returned.
400	BAD_REQUEST	We encountered an issue processing your request. This could be due to: - Missing information in the request. - Incorrect request data format. - Incorrect API endpoint. - Required service not configured for your account.	- Missing information or Incorrect data format errors: Carefully examine the data you're sending and ensure it matches the expected format and type for each parameter. Refer to our detailed API documentation for more information. Contact our support team at [email protected] for further assistance. - Service not configured errors: Contact our Support Team at [email protected] if the service you're trying to access is not enabled for your account.
401	UNAUTHORISED_ACCESS	API authentication failed. This could be due to: - Missing authentication header in the request header. - Incorrect authentication format. - Invalid authentication credentials.	- Ensure you have included the authorization header in the API request in the correct format. The header value should be in the `Basic <base64encoded_credentials>` format. - Ensure the authorization key used is valid. You can check this on your Bureau Dashboard. - Verify that the token is issued for the correct environment (sandbox or production).
403	MERCHANT_CREDITS_EXPIRED	Your account has run out of credits required to make API calls.	Contact our Support Team at [email protected] to get more credentials added to your account.
422	NO_RECORD_FOUND	We couldn't find any relevant information using your input (request) data.
443	MAX_RETRIES_EXCEEDED	The rate limit for the API has been exceeded.	Wait for the recommended time before retrying the request. Contact our Support Team at [email protected] to know the rate limit for your account.
500	INTERNAL_SERVER_ERROR	The server encountered an unexpected error while processing your request. These are rare.	Retry after some time. Contact our Support Team at [email protected] if the error persists.
503	INTERNAL_SERVICE_UNAVAILABLE	The server is not ready to handle the request.	Retry after some time. Contact our Support Team at [email protected] if the error persists.

Error Handling Recommendations

Here are some best practices for handling API errors in your integrations:

Logging: Record all API errors to facilitate troubleshooting and identify recurring issues. This helps pinpoint the root cause and improve your integration's resilience.
Retry Logic: Implement a retry mechanism with exponential backoff for transient errors like network issues or server overload. This avoids overwhelming the server with repeated requests.
Specific Error Codes: Utilize the specific error codes provided to tailor your error handling and provide more informative messages to your users.

Sample Error Responses

Below are sample error responses returned by our APIs.

Error Structure

The table below lists the parameters in the error response and gives a brief description of each.

Parameter	Data Type	Description
error	Object	Object that contains details about the error that occurred.
error.code	Integer	Error code. Common error codes: - 400 - 401 - 403 - 422 - 500 - 503
error.description	String	Parameter describing the error that occurred.
error.description	String	Summary of the error that occurred.
error.metadata		Other information about the error.
error.referenceId	String	Unique reference Id generated by Bureau for the request/error.
error.type	String	Type of error that occurred. Some possible values: - BAD_REQUEST - MERCHANT_CREDITS_EXHAUSTED - NO_RECORD_FOUND - INTERNAL_SERVER_ERROR - SERVICE_UNAVAILABLE
merchantId	String	Your unique identifier in Bureau's database.
requestId	String	Unique identifier generated by Bureau for the request. Quote this Id when you contact Bureau Support if you face issues with the API.
statusCode	Integer	HTTP status code for the response.
timestamp	Integer	Unix timestamp, in milliseconds, when the response was returned.

Sample 400 Error Response

{
  "error": {
    "code": 400,
    "description": "Request does not contain ifsc param in request body",
    "message": "IFSC is missing",
    "metadata": null,
    "referenceId": "",
    "type": "BAD_REQUEST"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 400,
  "timestamp": 1725268007691
}

{
  "error": {
    "code": 400,
    "description": "ifsc should be of 11 characters and 5th character should be 0.",
    "message": "IFSC is invalid",
    "metadata": null,
    "referenceId": "",
    "type": "BAD_REQUEST"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 400,
  "timestamp": 1725268037531
}

{
  "error": {
    "code": 400,
    "description": "",
    "message": "request is invalid",
    "metadata": null,
    "referenceId": "",
    "type": "BAD_REQUEST"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 400,
  "timestamp": 1725268061429
}

{
  "error": {
    "code": 400,
    "description": "",
    "message": "Rate Limit exceeded for the given account number",
    "metadata": null,
    "referenceId": "",
    "type": "BAD_REQUEST"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 400,
  "timestamp": 1724664760031
}

{
  "statusCode": 400,
  "error": {
    "code": 0,
    "type": "BAD_REQUEST",
    "message": "failed to read request body",
    "description": "",
    "referenceId": "f18a9868-689c-44f2-838d-5d8e494bc09b",
    "metadata": null
  },
  "timestamp": 1725267830137,
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA="
}

{
  "statusCode": 400,
  "error": {
    "code": 0,
    "type": "BAD_REQUEST",
    "message": "Signal is invalid",
    "description": "Request contains an invalid signal url path param",
    "referenceId": "ahyv774hrko4n1i=",
    "metadata": null
  },
  "timestamp": 1725273648103,
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA="
}

Sample 401 Error Response

{
  "data": null,
  "errors": {
    "status": 401,
    "errorCode": "UNAUTHORIZED",
    "service": "Overwatch"
  },
  "message": "",
  "meta": {
    "length": 0,
    "took": 0,
    "total": 0
  }
}

Sample 403 Error Response

{
  "error": {
    "code": 403,
    "description": "Merchant does not have access to this service",
    "message": "Credits for accessing the capability exhausted",
    "metadata": null,
    "referenceId": "UAHrkoM0Bcwod9c=",
    "type": "MERCHANT_CREDITS_EXHAUSTED"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 403,
  "timestamp": 1719402094855
}

Sample 422 Error Response

{
  "error": {
    "code": 422,
    "description": "",
    "message": "NO_RECORD_FOUND",
    "metadata": null,
    "referenceId": "",
    "type": "NO_RECORD_FOUND"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 422,
  "timestamp": 1725268611716
}

Sample 500 Error Response

{
  "error": {
    "code": 500,
    "description": "",
    "message": "failed to make request",
    "metadata": null,
    "referenceId": "",
    "type": "INTERNAL_SERVER_ERROR"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 500,
  "timestamp": 1724833171844
}

Sample 503 Error Response

{
  "error": {
    "code": 503,
    "description": "",
    "message": "SERVICE_UNAVAILABLE",
    "metadata": null,
    "referenceId": "",
    "type": "SERVICE_UNAVAILABLE"
  },
  "merchantId": "org_qMOPL369km74RKOz",
  "requestId": "RNlVKFM0BcwEDGA=",
  "statusCode": 503,
  "timestamp": 1721129999110
}