Error Codes & Handling

TickAtlas uses standard HTTP status codes. All error responses include a JSON body with details.

Error Response Format

All errors return a consistent JSON structure:

format

{
  "error": "Error Type",
  "message": "Human-readable description",
  "code": 400,
  "details": "Optional additional context"
}

Error Codes Reference

400

Bad Request

The request was malformed or missing required parameters.

400

{
  "error": "Bad Request",
  "message": "Parameter \"symbol\" is required",
  "code": 400
}

Fix: Check that all required parameters are included and correctly formatted.

401

Unauthorized

Missing or invalid API key.

401

{
  "error": "Unauthorized",
  "message": "Invalid API key",
  "code": 401
}

Fix: Verify your API key is correct and included in the X-API-Key header.

403

Forbidden

The API key does not have permission for this endpoint or IP is not whitelisted.

403

{
  "error": "Forbidden",
  "message": "API key does not have access to this endpoint",
  "code": 403
}

Fix: Check key permissions in your dashboard. Verify IP whitelist if enabled.

404

Not Found

The requested resource does not exist.

404

{
  "error": "Not Found",
  "message": "Symbol INVALID not found",
  "code": 404
}

Fix: Verify the symbol name, indicator, or endpoint path is correct. Use /v1/symbols to list available symbols.

429

Rate Limited

Too many requests in the current time window.

429

{
  "error": "Rate Limited",
  "message": "Rate limit exceeded. Retry after 60 seconds",
  "code": 429,
  "retry_after": 60
}

Fix: Implement exponential backoff. Consider upgrading your plan or caching responses.

500

Internal Server Error

An unexpected error occurred on our end.

500

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred",
  "code": 500
}

Fix: Retry the request after a brief delay. If persistent, contact support with the request details.

503

Service Unavailable

The service is temporarily unavailable (maintenance or overload).

503

{
  "error": "Service Unavailable",
  "message": "Service temporarily unavailable. Please try again later",
  "code": 503
}

Fix: Wait and retry. Check our status page for planned maintenance windows.

Error Handling Best Practices

Always check HTTP status codes

Don't assume success. Check that the status code is 200 before processing the response body.

Parse the error message

The message field provides specific details about what went wrong.

Implement retry logic

For 429 and 5xx errors, implement exponential backoff with jitter. Respect the Retry-After header.

Log errors for debugging

Log the full error response including timestamp, endpoint, and parameters for troubleshooting.

Example: Error Handling in Python

Python

import requests
import time

def api_request(endpoint, params, max_retries=3):
    url = f"https://tickatlas.com/v1/{endpoint}"
    headers = {"X-API-Key": "YOUR_API_KEY"}

    for attempt in range(max_retries):
        response = requests.get(url, headers=headers, params=params)

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 60))
            print(f"Rate limited. Retrying in {retry_after}s...")
            time.sleep(retry_after)
        elif response.status_code >= 500:
            wait = 2 ** attempt  # Exponential backoff
            print(f"Server error {response.status_code}. Retrying in {wait}s...")
            time.sleep(wait)
        else:
            error = response.json()
            raise Exception(f"API Error {error['code']}: {error['message']}")

    raise Exception("Max retries exceeded")

Complete Error Reference

For a comprehensive list of all error codes, including dashboard-specific errors and detailed troubleshooting guides, refer to our complete error documentation.

View Full Error Documentation