Error Handling

Error Response Format

All errors follow a consistent JSON format:

{
  "error": "ERROR_CODE",
  "message": "Human-readable description of the error"
}

Validation errors include a details array:

{
  "error": "VALIDATION_FAILED",
  "message": "Offer payload failed validation",
  "details": [
    "purchase_price_floor must be a positive number",
    "buy_rate must be >= 1.0"
  ]
}

HTTP Status Codes

Common Errors

SIGNATURE_INVALID

Your HMAC signature doesn't match. Common causes:

• Wrong HMAC secret
• JSON serialization mismatch (whitespace, key ordering)
• Request body was modified after signing

TIMESTAMP_EXPIRED

The X-Timestamp header is more than 5 minutes old. Check your server clock is synced via NTP.

VERSION_CONFLICT

Another update happened between your read and write. Fetch the latest version number and retry:

GET /api/v1/{funder}/offers/{dealId}
→ get current version
→ retry PUT/PATCH with new version

VALIDATION_FAILED

The offer payload failed business rule validation. Check the details array for specific field errors. Common issues:

• purchase_price_floor > purchase_price_ceiling
• buy_rate < 1.0
• max_upsell < 0
• num_payments_floor > num_payments_ceiling
• Fee floor > ceiling for adjustable fees
• Invalid base_frequency value

Rate Limits

Default rate limits per API key:

Rate limit headers are included in every response:

• X-RateLimit-Limit — requests allowed per window
• X-RateLimit-Remaining — requests remaining
• X-RateLimit-Reset — Unix timestamp when the window resets

When rate limited (429), wait until X-RateLimit-Reset before retrying.