Errors

Here’s a quick reference for all the error responses defined in the OpenAPI spec. All errors return application/json bodies with at least:

• code – the HTTP status

• message – a human-readable description

• optional errors – field-level details (on 400/500)

Keep an eye on the exact message text in the spec for each endpoint, but this table covers all of the HTTP error codes you’ll see.

API Rate Limits

• 5 requests per second per API key

• Uses a fixed window algorithm that resets every second

• Rate limiting is scoped per API key, so each key has its own independent limit

429 Response Details:

When the rate limit is exceeded, you'll receive an HTTP 429 response with the following:

{
  "code": 429,
  "message": "Rate limit exceeded. Please retry after the specified time.",
  "retryAfter": 1
}

The retryAfter field indicates the number of seconds (rounded up) until the rate limit window resets. This value will typically be 1 second or less, since the window resets every second.

Rate Limit Headers:

All API responses include the following headers (even when not rate-limited) to help you implement proactive backoff:

• X-RateLimit-Limit: The maximum number of requests allowed (5)

• X-RateLimit-Remaining: Number of requests remaining in the current window

• X-RateLimit-Reset: ISO 8601 timestamp indicating when the current window resets

Recommended Backoff Strategy:

1. Exponential backoff with jitter: When you receive a 429, wait for the retryAfter duration (or slightly longer) before retrying. For subsequent retries, you can implement exponential backoff with jitter to avoid thundering herd problems.

2. Monitor headers proactively: Use the X-RateLimit-Remaining header to throttle your request rate before hitting the limit. For example, if remaining is 1 or 2, you might want to slow down your request rate.

3. Batch operations: For order sync operations that might require many requests, consider batching or spacing out requests to stay within the 5 req/sec limit.