Errors

The API uses standard HTTP status codes and returns JSON error responses with structured error codes.

HTTP Status Codes

Error Response Format

All error responses return a JSON object with an error field:

{
  "error": "descriptive error message"
}

Some errors include an additional code field for programmatic handling:

{
  "error": "missing or invalid authentication",
  "code": "UNAUTHORIZED"
}

Global Error Code Catalog

These error codes can be used for programmatic error handling across all endpoints:

Example Response Bodies

UNAUTHORIZED (401)

{
  "error": "missing or invalid authentication",
  "code": "UNAUTHORIZED"
}

API_KEY_UNAUTHORIZED (401)

{
  "error": "API key is revoked or expired",
  "code": "API_KEY_UNAUTHORIZED"
}

FORBIDDEN (403)

{
  "error": "access denied",
  "code": "FORBIDDEN"
}

INSUFFICIENT_SCOPE (403)

{
  "error": "API key lacks scope: trade:orders",
  "code": "INSUFFICIENT_SCOPE"
}

RATE_LIMITED (429)

{
  "error": "rate limit exceeded",
  "code": "RATE_LIMITED"
}

VALIDATION_ERROR (400)

{
  "error": "invalid side: must be BUY or SELL",
  "code": "VALIDATION_ERROR"
}

NOT_FOUND (404)

{
  "error": "order not found",
  "code": "NOT_FOUND"
}

INTERNAL_ERROR (500)

{
  "error": "internal server error",
  "code": "INTERNAL_ERROR"
}

Common Errors by Category

Authentication

Orders

Time-in-Force

Rate Limits

Batch Operations

Handling Errors

import requests
import time

resp = requests.post(f"{BASE_URL}/orders", json=order, headers=headers)

if resp.status_code == 429:
    # Rate limited - wait and retry
    reset_time = int(resp.headers.get("X-RateLimit-Reset", 0))
    wait_seconds = max(1, reset_time - int(time.time()))
    time.sleep(wait_seconds)
    # Retry...

elif resp.status_code == 401:
    error = resp.json()
    code = error.get("code", "")
    if code == "API_KEY_UNAUTHORIZED":
        print("API key revoked - regenerate key")
    else:
        print("Auth error - check credentials")

elif resp.status_code == 503:
    # Platform paused - stop trading
    print("Platform is paused, stopping")

elif resp.status_code >= 400:
    error = resp.json().get("error", "unknown error")
    print(f"Error {resp.status_code}: {error}")

const resp = await fetch(`${BASE_URL}/orders`, {
  method: 'POST',
  headers: { ...authHeaders, 'Content-Type': 'application/json' },
  body: JSON.stringify(order),
});

if (resp.status === 429) {
  const resetTime = parseInt(resp.headers.get('X-RateLimit-Reset') ?? '0');
  const waitMs = Math.max(1000, (resetTime - Math.floor(Date.now() / 1000)) * 1000);
  await new Promise((r) => setTimeout(r, waitMs));
  // Retry...
} else if (resp.status === 401) {
  const { code } = await resp.json();
  if (code === 'API_KEY_UNAUTHORIZED') {
    console.error('API key revoked - regenerate key');
  }
} else if (!resp.ok) {
  const { error } = await resp.json();
  console.error(`Error ${resp.status}: ${error}`);
}

Idempotency

There are two independent mechanisms. Retrying an order safely requires the second one.

Order-hash uniqueness (automatic)

polygon_orders.order_hash is unique, so the same signed order can never be stored twice. Re-submitting one returns 409 Conflict — it does not return the original order.

Note that the response code is the generic ORDER_PLACEMENT_FAILED; the error message is duplicate order. Match on the 409 status together with that message, not on a dedicated code.

This protects the exchange's state, but on its own it is not enough for a client. If your request reached us and the response was lost, your retry sends the identical signed body and receives a 409. You will record the order as failed while it is in fact resting on the book. Re-signing and re-sending produces a different salt, a different hash, and therefore genuinely new exposure.

Idempotency-Key header (recommended for order placement)

Send one on POST /v1/orders and POST /v1/orders/batch. A repeat of the same key replays the original stored response — including the original success — so a retry after a lost response is safe. Keys are retained for 24 hours.

The UUID requirement is enforced on /v1/orders only. Send a UUID on both and you will satisfy either endpoint.

Derive the key from the order's content rather than generating a random one per attempt — a random key regenerated on retry defeats the whole mechanism. A UUID v5 over the order signature works well: stable across retries of the same order, distinct for a genuinely new one.

const res = await fetch("https://api.4rho.com/v1/orders", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": uuidv5(signedOrder.signature, NAMESPACE), // NOT uuidv4()
    ...authHeaders,
  },
  body: JSON.stringify(signedOrder),
});