Error Codes

The Payzava API uses standard HTTP status codes to indicate success or failure.

HTTP status codes

Error response format

All error responses follow this format:

{
  "success": false,
  "message": "Description of the error"
}

Common errors and solutions

401 — Missing x-api-key header

{
  "success": false,
  "message": "x-api-key header is required"
}

Solution: Include your API key in the x-api-key request header.

401 — Sandbox key used in production

{
  "success": false,
  "message": "Sandbox key cannot be used in production"
}

Solution: Use a production API key (prefixed with sk_live_) with the production base URL (https://prod.payzava.com/cp/api/v1).

401 — Invalid API key

{
  "success": false,
  "message": "Invalid API key"
}

Solution: Check that your API key is correct and has not been revoked. Regenerate from the dashboard if needed.

400 — Missing required fields

{
  "success": false,
  "message": "\"amount\" is required"
}

Solution: Check the API reference for the endpoint and ensure all required fields are included in the request body.

404 — Resource not found

{
  "success": false,
  "message": "Transaction not found"
}

Solution: Verify the transaction ID, payout ID, or refund ID is correct. Ensure you are using the right environment (sandbox vs production).

413 — Request body too large

{
  "success": false,
  "message": "Request entity too large"
}

Solution: The maximum request body size is 1MB. Reduce the size of your request payload.

429 — Rate limit exceeded

{
  "success": false,
  "message": "Too many requests"
}

Solution: You have exceeded the rate limit. Wait before retrying.

500 — Internal server error

{
  "success": false,
  "message": "Internal server error"
}

Solution: This is a server-side error on Payzava's end. Retry the request after a short delay. If the issue persists, contact support@payzava.com.