Overview

Error Codes

Payonify uses standard HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g., a required parameter was missing), and codes in the 5xx range indicate an error with Payonify's servers.

Error Types

Error Type	Description
invalid_request_error	The request was invalid in some way (e.g., missing required fields, invalid values)
api_error	An unexpected error occurred while processing the request
idempotency_error	An error related to the use of idempotency keys
authentication_error	Issues with authentication or authorization
rate_limit_error	The client has sent too many requests

Below is the list of possible error codes, along with their descriptions and possible causes. Ery error object linkts to this list in its doc_url attribute.

missing_credentials

Authorization header is missing or malformed. Use Basic authentication with your publishable key and secret key.

invalid_publishable_key

The publishable key provided does not exist or is invalid.

invalid_secret_key

The secret key provided is incorrect or does not match the publishable key.

unauthorized

You are not authorized to access this resource or perform this action.

parameter_invalid

One or more parameters provided in the request are invalid.

resource_missing

The requested resource does not exist.

charge_pending

This charge is still in a pending state and cannot be modified.

charge_failed

This charge has failed and cannot be modified.

charge_already_refunded

This charge has already been refunded and cannot be refunded again.

charge_invalid_state

The charge is in a state that doesn't allow this operation.

checkout_session_already_expired

The session has already expired and cannot be used.

internal_error

An unexpected error occurred. Please try again later.

authentication_error

Authentication with the payment provider failed.

provider_error

An error occurred on the payment provider's platform.

provider_unavailable

The payment provider is temporarily unavailable.

unexpected_error

An unexpected error occurred with the payment provider.

provider_gateway_timeout

The request to the payment provider timed out.

invalid_payment_info

The payment information provided is invalid.

payment_failed

The payment was declined by the provider.

processing_error

An error occurred while processing the payment.

rate_limit_exceeded

You have exceeded the rate limit. Please retry again later.

Handling Errors

When an error occurs, Payonify responds with:

1. An appropriate HTTP status code
2. A JSON body containing additional information about the error

Example error response:

Code
 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_invalid",
    "message": "The amount parameter is invalid.",
    "param": "amount"
  }
}

When handling errors in your application, we recommend:

• Check the HTTP status code first to determine the general category of error
• Examine the error.type to understand the general type of error
• Use the error.code to get the specific error condition
• Display error.message to your users or for debugging, as it provides a human-readable explanation
• For validation errors, check the error.param to identify which parameter caused the error

For persistent errors, please contact our support team.