CashPay Logo

Error Handling

Understand the common error responses from the CashPay API and how to handle them gracefully.

Error Response Format

When an API request fails, we return a response with an appropriate HTTP status code and a JSON body containing more details about the error. All error responses follow a standard format.

Standard Error Response

JSON
{
  "success": false,
  "error": "A human-readable error message.",
  "details": { ... } // Optional object with more specific error details
}

HTTP Status Codes

We use conventional HTTP status codes to indicate the success or failure of an API request. Here are the most common ones you will encounter during development.

  • 200 - OK

    The request was successful.

  • 401 - Unauthorized

    The request lacks valid authentication credentials. This is the **expected error** if you call a protected endpoint without providing a valid API key. This confirms the endpoint is working and secure.

  • 405 - Method Not Allowed

    You are trying to access an endpoint with the wrong HTTP method. For example, using `GET` (the default for browsers) on an endpoint that only accepts `POST`. This is the **expected error** in such cases and confirms the endpoint exists.

  • 400 - Bad Request

    Your request was authenticated, but the request body was improperly formatted or missing required parameters. The `details` object in the response will often contain field-specific errors.

  • 403 - Forbidden

    You are authenticated correctly, but your API key does not have permission to perform the requested action. This can happen if you try to modify a resource that does not belong to you.

  • 404 - Not Found

    The requested resource or URL could not be found. If you receive this, double-check that your URL path is correct.

  • 500 - Internal Server Error

    An unexpected error occurred on our servers. If this persists, please contact support.