Errors
API error responses, HTTP status codes, error categories, and debugging information.
Copy linkOverview
When a request to the Paystack API fails, the response always includes clear information about what went wrong and how to fix it. Each error follows a consistent structure that contains a human-readable message, a machine-readable code, and optional diagnostic information to help you debug quickly.
Paystack's API is RESTful and as such, uses conventional HTTP response codes to indicate the success or failure of requests.
Copy linkHTTP status codes
| Code | Description |
|---|---|
| 200 | Request was successful and intended action was carried out. Note that we will always send a 200 if a charge or verify request was made. Do check the data object to know how the charge went (i.e. successful or failed). |
| 201 | A resource has successfully been created. |
| 400 | A validation or client side error occurred and the request wasn't fulfilled. |
| 401 | The request wasn't authorized. This can be triggered by passing an invalid secret key in the Authorization header or the lack of one. |
| 404 | Request couldn't be fulfilled as the request resource doesn't exist. |
| 429 | The request rate limit has been exceeded. See Rate Limits for more information. |
| 5xx | Request couldn't be fulfilled due to an error on Paystack's end. This shouldn't happen, so please report as soon as you encounter any instance of this. |
Copy linkError response format
Every error response includes the same top-level fields:
| Field | Type | Description |
|---|---|---|
| status | Boolean | This lets you know if the request to the API was received and processed successfully or not. We recommend that you use this in combination with HTTP status codes to determine the result of an API call. |
| message | String | This is a brief description of the error that occurred. |
| meta | Object | An object containing additional information about the error. It contains a next_step key that provides a suggested action to resolve the issue. It may also contain other diagnostic information to help you debug the issue. |
| type | String | The type of error that occurred. This can be one of: api_error, validation_error, or processor_error. |
| code | String | A Paystack-defined error code that categorizes the error. This helps you quickly identify the type of error that occurred. |
| data | Object | This is generally not returned for error responses, but may be returned in some cases where the error is related to the data being processed. |
The meta object contains additional information that can be helpful in resolving the error. It generally contains a next_step key that provides a suggested action to resolve the issue, and may provide other diagnostic information to help you debug the issue.
Example: When a bulk transfer is rejected, the meta object indicates if any of the transfer recipients are invalid or blacklisted.
Copy linkError categories
Errors are grouped into categories to make them easier to understand and handle programmatically.
| Category | Description |
|---|---|
| api_error | This indicates that the error happened on the Paystack API. Errors here include attempts to access resources that an integration isn't authorized to access, or similar API-level issues. |
| validation_error | This indicates that the error is related to invalid data in the request. Errors here include missing or invalid parameters being passed to the API. |
| processor_error | This indicates that the error is related to the payment processor or gateway. Errors here include insufficient funds, blocked/expired cards, or other issues relayed by the payment processor. |
Copy linkCommon errors
Copy link401 Unauthorized
This error occurs when:
- An invalid secret key is passed in the Authorization header
- No Authorization header is provided
- The Authorization header format is incorrect
Solution: Verify that you're using a valid secret key and that your Authorization header is formatted correctly: Authorization: Bearer YOUR_SECRET_KEY
Copy link400 Validation Error
This error occurs when:
- Required parameters are missing
- Parameters have invalid formats
- The request body is malformed JSON
Solution: Check the error message and meta.next_step for specific guidance on which parameter is invalid.
Copy link404 Not Found
This error occurs when:
- The endpoint URL is incorrect
- The resource ID doesn't exist
- The API route is invalid
Solution: Verify that the endpoint URL is correct and that the resource exists.
Copy link429 Too Many Requests
This error occurs when your request rate exceeds the API's rate limits.
Solution: See Rate Limits for more information on how to handle rate limiting and best practices for staying within limits.
Copy linkError handling best practices
- Always check the HTTP status code in combination with the
statusfield in the response. - Use the error
codeto identify the type of error and handle it programmatically. - Read the
meta.next_stepfor guidance on resolving the issue. - Log errors with all available diagnostic information for debugging.
- Implement exponential backoff for retrying requests that fail with 5xx errors or rate limit (429) responses.
- Don't expose sensitive error details to users—log them securely and show user-friendly messages instead.