Boya API Error Handling Guide

This guide describes how the Boya API handles errors, the structure of error responses, and the different types of errors you might encounter when using the API.

Error Response Structure

When the Boya API encounters an issue processing a request, it returns an error response in JSON format. The response will include an HTTP status code, a human-readable message, and an optional error code for programmatic handling.

Example Error Response

   {
    "errorMessage": "Invalid request parameter: 'email' must be a valid email address",
    "status": 400
  }

Error Response Fields

• errorMessage: A human-readable message that describes the error in more detail.
• status: The HTTP status code corresponding to the error.

Common Error Response Codes

401 Unauthorized

Authentication failed. This can happen if the API key is missing, invalid, or expired.

Example:

{
    "errorMessage": "Unauthorized",
    "status": 401
  }

Possible Causes:

• No API key was provided in the request.
• The provided API key is invalid or expired.
• The API key does not have the necessary permissions for the requested resource.

403 Forbidden

The API key is valid but does not have permission to access the requested resource.

Example:

{
    "errorMessage": "Forbidden",
    "status": 403
  }

Possible Causes:

• The API key is restricted to certain resources.
• The API key does not have the necessary scope for the operation.

404 Not Found

The requested resource does not exist or is not accessible.

Example:

{
    "errorMessage": "Not Found",
    "status": 404
  }

Possible Causes:

• The resource ID provided does not match any existing resource.
• The resource is no longer available or has been deleted.

409 Conflict

The request could not be completed due to a conflict with the current state of the resource.

Example:

{
    "errorMessage": "Transaction already exists",
    "status": 409
  }

Possible Causes:

• Duplicate transaction or resource entry.
• Conflict between the current state of a resource and the requested update.

429 Rate Limit Exceeded

Rate Limit Exceeded

Example:

{
    "errorMessage": "You have exceeded the request limit. Please try again later.",
    "status": 429
}

Possible Causes:

• The API enforces limits to prevent abuse or excessive usage. This can be a global rate limit (e.g., requests per minute or hour) or specific to certain operations.
• Burst Traffic: If your application sends many requests in a short time (burst traffic), you might hit the limit even though your overall request rate is low.

500 Internal Server Error

An unexpected error occurred on the Boya API server. This is usually a temporary issue, and the Boya team is likely working to resolve it.

Example:

{
  "errorMessage": "An internal server error occurred",
  "status": 500
}

Possible Causes:

• An unexpected error on Boya’s servers.
• Temporary downtime or unavailability.

Best Practices for Error Handling

1. Log Errors: Always log errors on your end to help diagnose issues quickly.
2. Retry Logic: Implement retry logic for 500-range errors, as these are typically temporary.
3. Graceful Fallback: Provide appropriate feedback to users in case of failure. For instance, show a retry option for 500-range errors and validation messages for 400-range errors.
4. Review Error Messages: Regularly review Boya’s error messages and documentation to handle errors appropriately.
5. Contact Support: For persistent issues, contact Boya’s support team at support@boyahq.com.

Conclusion

Understanding and handling errors effectively is crucial to building a robust integration with Boya’s API. Use this guide as a reference to manage error responses and ensure your application is resilient and user-friendly.