Errors

Unsuccessful requests return an HTTP error status and a JSON body.

Status codes

Status	Meaning	What to do
401	The API key is missing, invalid, or revoked.	Check the token or create a replacement.
403	The account or token cannot make the request.	Contact Xash support.
404	The path does not exist.	Check the base URL and endpoint path.
422	A field is invalid or the wallet balance is insufficient.	Read errors, correct the request, and try again.
429	Too many top-up requests were sent.	Wait for Retry-After, then retry with the same ref.
500	The request could not be completed.	Retry with the same ref. Contact support if it continues.

Validation errors

HTTP 422 returns a message and field-level errors:

{
  "message": "The recipient field must be a valid number.",
  "errors": {
    "recipient": ["The recipient field must be a valid number."]
  }
}

Common causes include:

• recipient is missing or is not a valid phone number.
• units is missing, is not positive, or is more than the available balance.
• ref is missing.

Top-up statuses

A top-up response uses HTTP 201 even when the returned status is not completed. Always read the status before updating the customer order.

• completed: the top-up succeeded.
• failed: the top-up did not complete. Read failure_reason.
• pending: wait and check the record again.
• under_review: do not submit a duplicate. Keep the uuid and ref, and contact Xash support if needed.

See Top-ups for the full status table.

Retry safely

Use the same ref when retrying after a network error, HTTP 429, or HTTP 500. Use a new ref only for a new customer request.