Skip to main content

​
Connection-Level Errors

Before receiving HTTP status codes, you may encounter connection-level errors: Common connection errors:
  • ECONNRESET - Connection reset by peer
  • EPIPE - Broken pipe
  • ECONNREFUSED - Connection refused
  • ETIMEDOUT - Connection timeout
  • SocketError: other side closed - ALB timeout (10 minutes)
  • 14 UNAVAILABLE (gRPC) - Stream dropped

Connection Issues Guide

See the full Connection Issues guide for detailed troubleshooting of network errors, ALB timeouts, gRPC streams, keepalive settings, and reconnection strategies

​
HTTP Status Codes

4xx errors are client-side errors. These indicate problems with your request that you need to fix (invalid data, missing authentication, wrong permissions, etc.). Debug these by examining your request.5xx errors are server-side errors. These indicate problems on the API server. Retry these with exponential backoff.

​
400 Bad Request

Your request format is invalid. Common causes:
  • Invalid JSON format
  • Missing required fields
  • Invalid field values (wrong type, out of range, etc.)
  • Invalid parameter combinations
Solution: Check the error message in the response for specific details about what’s wrong.

​
401 Unauthorized

Your JWT token is missing, invalid, or expired. Solution: Request a new token from Auth0 and retry your request. See Authentication for detailed troubleshooting.

​
403 Forbidden

Your token is valid but doesn’t have the required scope for the endpoint. Solution: Contact support to request additional scopes added to your credentials. See Authentication for scope details.

​
404 Not Found

The endpoint or resource doesn’t exist. Common causes:
  • Incorrect API path
  • Resource ID doesn’t exist
  • Typo in the URL
Solution: Verify the endpoint path and resource ID are correct.

​
405 Method Not Allowed

The HTTP method (GET, POST, etc.) is not supported for this endpoint. Common causes:
  • Using GET on a POST-only endpoint
  • Using POST on a GET-only endpoint
Solution: Check the API documentation for the correct HTTP method.

​
409 Conflict

The request conflicts with the current state of the resource. Common causes:
  • Duplicate order with same ClOrdID
  • Attempting to cancel an already-filled order
  • Resource already exists
Solution: Check the current state of the resource and adjust your request.

​
413 Payload Too Large

Your request body exceeds the maximum allowed size. Common causes:
  • Sending too many items in a bulk request
  • Large text fields or descriptions
  • Batch operations with too many records
Solution: Reduce the request size or split into multiple smaller requests.

​
422 Unprocessable Entity

Your request is well-formed but contains semantic errors. Common causes:
  • Invalid business logic (e.g., order quantity exceeds position limits)
  • Instrument not tradable in current state
  • Violates trading rules or risk limits
Solution: Check the error message for specific validation failures.

​
429 Too Many Requests

You’ve exceeded the rate limit. Solution: Check the Retry-After header in the response and wait that long before retrying. See Rate Limits for details and troubleshooting.

​
500 Internal Server Error

An unexpected error occurred on the server. Solution: These are usually temporary. Retry your request after a short delay (1-2 seconds). If errors persist for more than a few minutes, contact support.

​
502 Bad Gateway

The API gateway cannot reach the backend service. Solution: This usually resolves within 60 seconds. Retry your request with exponential backoff. If issues persist, contact support.

​
503 Service Unavailable

The API is temporarily unavailable. Solution: This usually resolves within 60 seconds. Retry your request with exponential backoff. If issues persist, check the status page or contact support.

​
504 Gateway Timeout

Your request took too long to process (over 30 seconds). Common causes:
  • Large data queries without pagination
  • Complex report generation
  • Slow network connections
Solutions:
  • Use pagination for large result sets (limit/offset parameters)
  • Break large operations into smaller requests
  • Download reports as files rather than querying all data
  • Consider polling for status updates instead of waiting synchronously

​
Retry Strategy

Retry these errors with exponential backoff:
  • 429 (rate limit) - Always retry with backoff
  • 500, 502, 503, 504 (server errors) - Retry up to 3-5 times
Don’t retry these errors:
  • 400 (bad request) - Fix your request instead
  • 401 (unauthorized) - Get a new token first
  • 403 (forbidden) - Request won’t succeed without additional scopes
  • 404 (not found) - Resource doesn’t exist
  • 405 (method not allowed) - Use the correct HTTP method
  • 409 (conflict) - Resolve the conflict first
  • 413 (payload too large) - Reduce request size
  • 422 (unprocessable entity) - Fix validation errors

​
Exponential Backoff

Implement this retry pattern: 
Attempt 1: Immediate
Attempt 2: Wait 1 second
Attempt 3: Wait 2 seconds
Attempt 4: Wait 4 seconds
Attempt 5: Wait 8 seconds
Max: 5 attempts, ~15 seconds total
For 429 errors, use the Retry-After header value instead of the exponential backoff schedule.

​
Intermittent Failures

My request works sometimes but fails other times This could indicate:
  • Intermittent rate limiting - You’re close to the rate limit threshold
  • Token expiration - Your token expires mid-session
  • Network issues - Temporary connectivity problems
Solution: Implement proper error handling with retries for transient errors (429, 502, 503, 504).

​
Debugging Failed Requests

How to debug:
  1. Check response body: Error messages include details about what went wrong
  2. Log request/response: Keep records of your API calls for debugging
  3. Test with curl: Isolate whether the issue is with your code or the API
  4. Verify token: Decode your JWT at jwt.io to check claims and expiration
  5. Check environment: Ensure you’re using the correct API endpoint for your environment

​
Logging Best Practices

Which identifiers should be logged? At minimum, log these identifiers for troubleshooting:
  • accountId - Trading account
  • orderId - Order identifier
  • execId - Execution identifier
  • tradeId - Trade identifier
  • traceId - Request trace ID (when present in responses)
Example log entry: 
2024-01-15 10:30:45 | ORDER_SUBMITTED | accountId=acc_123 | orderId=ord_456 | instrument=tec-nfl-sbw-2026-02-08-kc | side=buy | qty=100
Should error text be used for logic? No. Never parse error message text in your code. Use instead:
  • Structured error codes
  • HTTP status codes
  • Specific error fields in response
Error message text may change. Error codes are stable.

​
Reporting Issues

Contact support with:
  • Environment (dev, preprod, prod)
  • Timestamp of the issue
  • Request details (endpoint, method, sanitized request body)
  • Response (status code, error message)
  • Your Client ID (never share your Client Secret)
  • Relevant identifiers (accountId, orderId, tradeId, traceId)