Reference

Error Handling

CamelPay returns consistent error responses with HTTP status codes and machine-readable error details.

HTTP Status Codes

Code	Meaning	Action
`200`	Success	Process response
`201`	Created	Resource created
`400`	Bad Request	Check request body and parameters
`401`	Unauthorized	Verify API key or JWT token
`402`	Payment Required	Insufficient wallet balance
`403`	Forbidden	Missing scope on your API key, or account not KYC-verified
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Duplicate idempotency key or resource
`422`	Unprocessable Entity	Validation failed — check errors array
`429`	Too Many Requests	Rate limit exceeded — implement backoff
`500`	Server Error	Retry with exponential backoff
`503`	Service Unavailable	A feature flag is temporarily disabled

Error Response Format

json

{
  "success": false,
  "data": null,
  "message": "Validation failed",
  "errors": [
    {
      "field": "phone_number",
      "message": "invalid format"
    }
  ]
}

Retry Strategy

For 5xx errors and network failures, use exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      if (error.status >= 500 || !error.status) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else {
        throw error; // Don't retry client errors
      }
    }
  }
}

Error Code Reference

Code	Field	Message	Fix
400	`slug`	payment page not found	Verify slug exists
400	`amount`	must be >= 500	Increase amount
401	—	missing X-API-Key header	Add API key header
401	—	invalid or expired API Key	Check key validity
402	—	insufficient wallet balance	Top up wallet
403	—	insufficient scopes	Grant the required scope to this key
403	—	KYC verification required	Complete verification before creating pages/payouts
409	—	duplicate idempotency key	Use a new key
422	`phone_number`	invalid format	Use E.164 format
429	—	rate limit exceeded	Implement backoff