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

CodeDescription
200Request 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).
201A resource has successfully been created.
400A validation or client side error occurred and the request wasn't fulfilled.
401The request wasn't authorized. This can be triggered by passing an invalid secret key in the Authorization header or the lack of one.
404Request couldn't be fulfilled as the request resource doesn't exist.
429The request rate limit has been exceeded. See Rate Limits for more information.
5xxRequest 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:

FieldTypeDescription
statusBooleanThis 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.
messageStringThis is a brief description of the error that occurred.
metaObjectAn 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.
typeStringThe type of error that occurred. This can be one of: api_error, validation_error, or processor_error.
codeStringA Paystack-defined error code that categorizes the error. This helps you quickly identify the type of error that occurred.
dataObjectThis 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.

CategoryDescription
api_errorThis 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_errorThis 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_errorThis 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

  1. Always check the HTTP status code in combination with the status field in the response.
  2. Use the error code to identify the type of error and handle it programmatically.
  3. Read the meta.next_step for guidance on resolving the issue.
  4. Log errors with all available diagnostic information for debugging.
  5. Implement exponential backoff for retrying requests that fail with 5xx errors or rate limit (429) responses.
  6. Don't expose sensitive error details to users—log them securely and show user-friendly messages instead.