Errors and rate limits

Error shape

All API errors follow:

{
  "error": {
    "code": "validation_error",
    "message": "Validation failed",
    "details": {}
  }
}

Common status codes

• 200: accepted (typically idempotent replay)
• 201: created
• 400: parameter missing / malformed request
• 401: missing or invalid bearer token
• 409: conflict (for example identifier conflict)
• 422: validation error
• 429: rate limited

Rate limits

Requests are throttled per IP and per token. If you receive 429, retry with exponential backoff.

Recommended strategy:

1. Retry after a short delay
2. Back off progressively
3. Keep using external_id for idempotent retries