Status Codes

This page documents all HTTP status codes returned by the Phoenix Pay API, along with their meanings and common causes.

HTTP Status Codes

Success Codes

Status	Name	When Used
`200 OK`	Success	GET requests, successful updates
`201 Created`	Resource Created	POST requests that create a new deposit or payout

Client Error Codes

Status	Name	Description
`400 Bad Request`	Invalid Request	The request is malformed or missing required parameters. The `error` field in the response describes which parameter is missing or invalid.
`401 Unauthorized`	Authentication Failed	No valid authentication token was provided. The token may be missing, expired, have an invalid signature, or be missing the required audience claim.
`403 Forbidden`	Insufficient Permissions	The token is valid but the authenticated user does not have permission for the requested action. Commonly returned when a tenant user tries to access admin-only endpoints.
`404 Not Found`	Resource Not Found	The requested resource does not exist, or it belongs to a different tenant. Phoenix Pay does not distinguish between "does not exist" and "belongs to another tenant" to prevent information leakage.
`422 Unprocessable Entity`	Processing Error	The request was syntactically valid but could not be processed. Common causes: no PSP configured for the currency, duplicate reference ID, or PSP rejected the request.
`429 Too Many Requests`	Rate Limited	You have exceeded the rate limit. Wait for the duration specified in the `Retry-After` header before retrying.

Server Error Codes

Status	Name	Description
`500 Internal Server Error`	Server Error	An unexpected error occurred on the server. The response body contains `{"error": "internal_error"}`. If this persists, contact support.

Error Response Format

All error responses follow a consistent format:

Error response

{
  "error": "description of the error"
}

The error field is always a string containing a human-readable description of what went wrong.

Common Error Messages

Authentication Errors (401)

Error	Cause	Resolution
`"unauthorized"`	Missing `Authorization` header	Include `Authorization: Bearer <token>` in your request
`"unauthorized"`	Token has expired	Request a new token using the client credentials grant
`"unauthorized"`	Invalid token signature	Ensure you are using a valid token from the correct Zitadel instance
`"unauthorized"`	Wrong audience claim	Include the correct project scope when requesting the token

Validation Errors (400)

Error	Cause	Resolution
`"missing required parameter: reference_id"`	The `reference_id` field is missing or empty	Provide a unique `reference_id` string
`"missing required parameter: amount"`	The `amount` field is missing or empty	Provide the amount as a decimal string
`"missing required parameter: currency"`	The `currency` field is missing or empty	Provide a currency code (e.g., `"USDT"`, `"ETB"`)
`"missing required parameter: destination_id"`	Payout is missing `destination_id`	Provide the destination ID from the List Destinations endpoint

Processing Errors (422)

Error	Cause	Resolution
`"no_psp_configured"`	No PSP is configured for the requested currency in your tenant	Configure a PSP that supports the requested currency via the admin panel or config API
`"has already been taken"`	The `reference_id` is already in use for your tenant	Use a unique `reference_id` for each payment
PSP-specific error	The PSP rejected the payment request	Check the error message for details; verify your PSP credentials are correct

Permission Errors (403)

Error	Cause	Resolution
`"forbidden"`	Tenant user accessing admin endpoints	Admin endpoints (`/api/admin/*`) are restricted to platform users

Payment Status Values

These are the possible values for the status field on payments, not HTTP status codes. See Payment Lifecycle for the full state machine.

Status	Description	Terminal?
`pending`	Payment record created, initial state	No
`awaiting_payment`	Waiting for customer to complete payment	No
`processing`	Payment detected, being confirmed by PSP	No
`partial`	Partial amount received (crypto deposits)	No
`settled`	Payment completed successfully	Yes
`failed`	Payment failed or was rejected	Yes
`expired`	Payment window expired before completion	Yes
`cancelled`	Payment was cancelled	Yes

Terminal means no further status changes are possible. Once a payment reaches a terminal state, all subsequent status update attempts are silently ignored.

PSP Identifiers

Value	PSP	Type
`nowpayments`	NOWPayments	Crypto payments
`chapa`	Chapa	Fiat payments (ETB)

Payment Types

Value	Description
`deposit`	Inbound payment (customer pays you)
`payout`	Outbound payment (you pay a recipient)

Status Codes

On this page