Testing - KryptaPay API

Learn about error handling when using the API.

Error Handling

The API uses standard HTTP status codes.

Status	Description
`200`	Success
`201`	Resource created
`400`	Bad request
`401`	Unauthorized
`403`	Forbidden
`404`	Resource not found
`409`	Conflict
`422`	Validation error
`429`	Too many requests
`500`	Internal server error

Example error response:

{
  "error": {
    "code": "validation_error",
    "message": "The amount must be greater than zero."
  }
}

Transaction Failure Codes

When a transaction cannot be completed, the API returns a machine-readable failure code along with a human-readable message. Use these codes to determine the appropriate action for your application.

Response Format

{
  "ok": false,
  "error": {
    "code": "string",
    "message": "string",
    "details": "string"
  }
}

Failure Codes

Failure Code	Description	Recommended Action
`INSUFFICIENT_FUNDS`	The customer does not have enough balance.	Ask the customer to top up their account and retry.
`INVALID_ACCOUNT`	The destination account or wallet does not exist.	Verify the account details before retrying.
`INVALID_PHONE_NUMBER`	The provided phone number is invalid.	Validate the phone number format.
`ACCOUNT_BLOCKED`	The customer’s account is blocked or suspended.	Ask the customer to contact their provider.
`ACCOUNT_CLOSED`	The destination account has been closed.	Request updated account information.
`PAYMENT_DECLINED`	The payment was declined by the provider.	Inform the customer and allow another payment method.
`PAYMENT_EXPIRED`	The payment authorization expired before completion.	Create a new payment request.
`TRANSACTION_CANCELLED`	The customer cancelled the transaction.	Allow the customer to initiate a new payment.
`TRANSACTION_TIMEOUT`	The provider did not respond within the expected time.	Retry using an idempotency key.
`DUPLICATE_TRANSACTION`	A transaction with the same idempotency key already exists.	Retrieve the existing transaction instead of creating a new one.
`LIMIT_EXCEEDED`	The transaction exceeds provider or merchant limits.	Reduce the amount or contact support.
`INVALID_AMOUNT`	The requested amount is invalid.	Ensure the amount is within supported limits.
`INVALID_CURRENCY`	The specified currency is not supported.	Use one of the supported currencies.
`MERCHANT_NOT_ACTIVE`	The merchant account is inactive.	Contact KryptaPay Support.
`PROVIDER_UNAVAILABLE`	The payment provider is temporarily unavailable.	Retry later with exponential backoff.
`NETWORK_ERROR`	A network error occurred while processing the transaction.	Retry the request safely.
`INTERNAL_ERROR`	An unexpected server error occurred.	Retry later or contact support if the issue persists.
`COMPLIANCE_REJECTED`	The transaction failed compliance or regulatory checks.	Contact support for further guidance.
`FRAUD_SUSPECTED`	The transaction was blocked by fraud detection systems.	Do not retry automatically. Contact support if necessary.
`UNKNOWN_ERROR`	An unknown error occurred.	Retry later or contact support.

Best Practices

Always use the failure_code field for programmatic handling. The failure_message is intended for debugging and may change over time.

When retrying failed requests, always include the same Idempotency-Key to prevent duplicate transactions.

Next Steps

Going live

Things to set to move from your sandbox account to live payments.

​Error Handling

​Transaction Failure Codes

​Response Format

​Failure Codes

​Best Practices

​Next Steps

Going live

Error Handling

Transaction Failure Codes

Response Format

Failure Codes

Best Practices

Next Steps