Errors

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.

HTTP Codes
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 was not fulfilled.
401	The request was not authorized. This can be triggered by passing an invalid secret key in the authorization header or the lack of one.
404	Request could not be fulfilled as the request resource does not exist.
5xx	Request could not 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.

Error response format

Every error response includes the same top-level fields:

Keys
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 the following: `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 about 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.

For example, when a bulk transfer is rejected, the meta object indicates if any of the transfer recipients are invalid or blacklisted.

Sample Validation Error

1{
2  "status": false,
3  "message": "Email Address is required",
4  "meta": {
5    "nextStep": "Provide all required params "
6  },
7  "type": "validation_error",
8  "code": "missing_params"
9}

Not sure where to look? Try search

Type the error or keywords into the search bar at the top of the page. If you don’t find what you’re looking for, contact us, we’re happy to help.

Error categories

Errors are grouped into categories to make them easier to understand and handle programmatically.

Error Categories
api_error String	This indicates that the error happened on the Paystack API. Errors here include attempts to access resources that an integration is not authorized to access, or similar API-level issues.
validation_error String	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 String	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.