Errors and rate limits

How both APIs report failure, which errors are retryable, and how rate limits behave on each key. Use this page when your client hits something other than a 200.

Both APIs return errors in a consistent JSON envelope:

{
  "errors": {
    "code": "optional_machine_readable_code",
    "detail": "Error message describing the issue"
  }
}

The HTTP status code tells you what went wrong. The detail string gives the specifics. Some Trading API errors also include code; use it for client branching when present, but keep displaying detail to humans.

Status codes

Status	Meaning	What it means	What to do
307	Temporary redirect	Your request is being forwarded to the routing layer that fulfills inference. The Location header points to the target.	Follow the redirect with the same method, body, and Authorization header. Most clients do this automatically. cURL needs -L. See Request routing and redirects.
400	Bad request	Malformed body or invalid parameter types.	Fix the request. Check required fields and parameter types against the OpenAPI block on the relevant endpoint page. Don't retry as-is.
401	Unauthorized	Missing or invalid API key. On the Trading API, also fires for invalid signatures or stale timestamps.	Verify the key in the dashboard. Check that your auth header is Authorization: Bearer ... (Consumption) or that signature, timestamp, and fingerprint headers are correct (Trading). Don't retry without fixing.
402	Payment required	Insufficient USD balance, or no token capacity available for this instrument.	Add credits, enable auto-reload, or wait for the system to top up automatically. Retry after a short delay; the next request usually goes through once balance replenishes.
404	Not found	Most commonly: invalid instrument string in the model parameter. Also fires for unknown order IDs, market IDs, etc.	Check the value against the catalog at Current instruments or https://thegrid.ai/instruments.json. Don't retry.
422	Validation error	Request is well-formed but a parameter value is out of range or structurally invalid. Common causes: temperature outside 0–2, malformed tools schema, invalid response_format.	Read the detail. Fix and resubmit. Don't retry as-is.
429	Rate or concurrency limit exceeded	You exhausted an inference concurrency slot or a Trading API submission bucket.	Back off and retry. Honor Retry-After when present. Use the limit-specific headers described below to pace later requests.
500	Internal server error	Server-side issue, often supplier transient errors surfaced through the API.	Retry with exponential backoff. If persistent, contact [e-mail].
503	Service unavailable / balance replenishing	Temporary supplier unavailability, or the system is replenishing your balance.	Wait 1 to 3 seconds and retry. The system handles supplier failover automatically; we don't bill your request if it doesn't complete.

Retry guidance

Always retry: 402, 429, 500, 503, and any other 5xx. These are transient and a backoff loop fixes them. Don't retry 400, 401, 404, or 422 without changing the request first; you get the same error.

A reasonable retry policy:

import time, random

def call_with_retry(fn, max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return fn()
        except RetryableError as e:
            if attempt == max_attempts - 1:
                raise
            delay = min(2 ** attempt + random.random(), 30)
            time.sleep(delay)

Cap the backoff somewhere sensible (e.g., 30 seconds) so you don't stall a worker indefinitely. Honor Retry-After when the server sends it.

Backup routing transparency

We route around supplier failures automatically. If the primary supplier for an instrument is unavailable, we try the next one. Your client doesn't see which supplier served the request, and you don't need failover code in your application. If a request fails entirely or returns a response that doesn't meet the instrument's specification, we don't bill you for it.

This means you should treat 5xx errors as transient by default. Most resolve on retry without any action on your end.

Rate limits

The Consumption and Trading APIs enforce different limits. Do not assume a single requests-per-minute value applies to both APIs, or that every endpoint returns rate-limit headers.

Consumption API: concurrent inference requests

When concurrency protection is active, the Consumption API limits the number of inference requests a user can have in flight at once. Chat Completions, Responses, and Anthropic Messages requests share this concurrency allowance. A request occupies one slot until it finishes, so a long-running stream holds its slot longer than a short non-streaming request.

Responses subject to the concurrency limit include:

• x-ratelimit-limit: your current maximum number of concurrent inference requests.
• x-ratelimit-remaining: the number of slots available after the current admission decision.
• Retry-After: on a 429, the number of seconds to wait before trying again.

Your effective concurrency allowance can increase with funded balance. Treat x-ratelimit-limit as the effective value for the current user rather than hard-coding a tier value. A Consumption API concurrency 429 uses the machine-readable code concurrency_limit_exceeded.

Trading API: order submissions

Create-order submissions are limited per user and market. The Trading and Exchange order-creation routes share that bucket, so switching routes does not provide a second allowance. The limit counts submissions, not fills, and does not accumulate unused burst capacity.

Before placing orders, call GET /v1/account/limits?market_id=... with the exact market_id returned by GET /v1/markets. Pace create-order requests from order_rate_limits.max_orders_per_second. max_orders_per_minute is the corresponding derived minute value, not a separate fill counter.

Create-order responses subject to this limit include:

• x-ratelimit-limit: the maximum accepted create-order submissions per second for this user and market.
• x-ratelimit-remaining: the submissions remaining in the current one-second window.
• Retry-After: on a 429, the number of seconds to wait before retrying.

Bulk cancellation has a separate account-wide throttle and does not consume the create-order bucket. Pace bulk-cancel requests from their response headers. Trading reads and other endpoints are not guaranteed to return order-submission headers.

When you hit a 429:

1. Read Retry-After if present and wait at least that long.
2. If absent, use exponential backoff with jitter starting at 1 second.
3. For inference, reduce parallel requests or queue them client-side.
4. For order creation, refresh GET /v1/account/limits?market_id=... and pace each user-market pair independently.
5. Make retries idempotent. For order creation, reuse a deterministic client_order_id so a lost response cannot create a duplicate order.

Trading API specifics

The Trading API surfaces the same error shape, with a few extras:

• 401 from the Trading API is most often a signing error. Check timestamp drift first (your clock vs. server time), then the message format you signed (<timestamp><METHOD><path><body>), then the fingerprint header. See Authentication.
• 409 fires on order operations with state conflicts (e.g., cancelling an already-cancelled order). Don't retry; the state is final.
• 422 on order placement usually means a price or quantity violates instrument rules. Limit-order price must be a decimal string such as "0.68", not a JSON number. Common code values include validation_error, quantity_below_min_order_size, quantity_above_max_order_size, lot_size_violation, tick_size_violation, insufficient_available_balance, and insufficient_inventory_or_funds. Order-control 422s include errors.detail, errors.code, and errors.context with submitted price / quantity, client_order_id when supplied, and limits such as min_order_size, lot_size, and tick_size.
• 422 price_collar_violation means a limit price was outside an active server-side reference-price band. Refresh /v1/markets to read price_collar_pct and submit a price inside the band. Keep independent client-side price bounds; a collar is a backstop, not a complete trading-safety policy.
• 422 on GET /v1/orders?status=... means the filter value is not recognized. Supported order status filters include open, active, pending, partially_filled, cancellation_pending, filled, closed, cancelled, expired, and rejected.
• 403 with auto_mode_trading_restricted means the account is still in Auto Mode. Switch to Advanced Mode before placing, updating, or cancelling orders.

Trading order limits count create-order submissions, not fills. Read the effective per-user, per-market value from GET /v1/account/limits?market_id=..., pace against order_rate_limits.max_orders_per_second, and honor retry-after on 429.

The full Trading API error catalog is documented in the OpenAPI blocks on the Trading API page.