Copy page

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. Every error object links to this list in its doc_url attribute.

Authentication Errors

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.

account_suspended

The account associated with the API key used in the request has been suspended. Please contact support.

api_key_revoked

The API key used in the request has been revoked.

invalid_credentials

The credentials provided are invalid.

invalid_webhook

A webhook endpoint has not been configured for the project associated with the API key used in the request.

Request Validation Errors

parameter_invalid

One or more parameters provided in the request are invalid.

parameter_missing

A required parameter is missing from the request.

payment_parameter_invalid

A payment parameter provided in the request is invalid.

resource_missing

The requested resource does not exist.

invalid_request_data

The request data is malformed or cannot be decoded.

invalid_payment_method

The payment method provided is not supported or is invalid.

invalid_destination

The payout destination provided is not supported or is invalid.

Charge Errors

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.

charge_confirmation_failed

The charge confirmation failed.

charge_cancellation_failed

The charge cancellation failed.

Refund Errors

refund_failed

The refund operation failed.

Payout Errors

channel_partner_not_found

A payout channel partner has not been configured for the project associated with the API key used in the request.

b2c_not_allowed

B2C payouts are not enabled for the project associated with the API key used in the request.

Checkout Errors

checkout_session_already_expired

The session has already expired and cannot be used.

API and Gateway Errors

internal_error

An unexpected error occurred. Please try again later.

gateway_error

An error occurred while communicating with the payment gateway.

Provider Errors

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": "Validation failed for amount: must be greater than 0",
    "param": "amount",
    "doc_url": "https://docs.payonify.com/errors#parameter_invalid"
  }
}

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.