Error Codes

Aurax Pay uses standard HTTP status codes. All error responses are JSON with an error field and optional details for validation errors.

Error response format

Error response

{
  "error": "Validation failed",
  "details": {
    "amount": ["Number must be greater than or equal to 500"],
    "buyerPhone": ["Invalid phone number format"]
  }
}

HTTP status codes

Status	Meaning	Common cause
200	OK	Request succeeded
201	Created	Resource created (payment initiated)
400	Bad Request	Validation error, missing field, or invalid value
401	Unauthorized	Missing or invalid API key
403	Forbidden	Key lacks required permission, or merchant not active
404	Not Found	Transaction or resource does not exist
409	Conflict	Duplicate idempotency key with different parameters
429	Too Many Requests	Rate limit exceeded — back off and retry
500	Internal Server Error	Something went wrong on our end — contact support
503	Service Unavailable	Temporary outage — retry with exponential backoff

Rate limits

API endpoints are rate-limited to protect the platform:

Endpoint group	Limit
POST /v1/payments	100 requests / minute
GET /v1/payments	300 requests / minute
All other /v1/* routes	200 requests / minute

When rate limited, the response is 429 with a Retry-After header indicating when you can retry.

Handling errors in code

Node.js — robust error handling

async function collectPayment(data) {
  const res = await fetch("token-string">'https:"token-comment">//api.auraxpay.net/v1/payments', {
    method: "token-string">'POST',
    headers: {
      "token-string">'Content-Type': "token-string">'application/json',
      "token-string">'x-api-key': process.env.AURAX_API_KEY,
    },
    body: JSON.stringify(data),
  })

  const body = await res.json()

  if (res.status === 400) {
    "token-comment">// Validation error — fix your request
    throw new Error("token-string">'Validation: ' + JSON.stringify(body.details))
  }

  if (res.status === 401 || res.status === 403) {
    "token-comment">// Auth error — check your API key
    throw new Error("token-string">'Auth error: ' + body.error)
  }

  if (res.status === 429) {
    "token-comment">// Rate limited — wait and retry
    const retryAfter = res.headers.get("token-string">'Retry-After') || 60
    await sleep(retryAfter * 1000)
    return collectPayment(data) "token-comment">// retry
  }

  if (!res.ok) {
    throw new Error("token-string">'Aurax API error ' + res.status + "token-string">': ' + body.error)
  }

  return body.transaction
}