API Error Handling and Status Codes Guide

When building financial applications, backtesting systematic trading models, or conducting academic research, handling API responses accurately is critical. The algoseek Datasets API provides consistent, structured error responses to help quantitative researchers and engineering teams seamlessly troubleshoot issues and maintain institutional-grade reliability.

All errors returned by the algoseek API follow a standardized JSON format. Below is a guide to the common error scenarios, their meanings, and how your systems should handle them.

To see a summary table of common error codes, go to Error Handling Summary.

422 Unprocessable Entity: Validation Errors#

Unlike other error responses that return a simple detail string, the 422 status code returns an array of validation errors. This format provides granular insights into the client-side issue, including the error type, the exact location of the error within the request (loc), a detailed message (msg), and additional context (ctx).

Error Response Example:

{
    "detail": [
        {
            "msg": "The following columns do not exist in the dataset: {column}",
            "type": "value_error",
            "loc": [
                "query",
                "filters"
            ],
            "input": "",
            "ctx": {
                "cause": "UnprocessableEntityException"
            }
        }
    ]
}

Common Use Cases & How to Solve Them:

• Invalid Columns: (As shown in the example above) Querying a column name that does not exist in the requested dataset's schema.
• Solution: Query the GET /api/v1/meta/datasets/{dataset_id}/columns endpoint to retrieve a list of valid fields before constructing your filters.
• Dates Outside Entitlement Window: Querying a date that falls outside the active subscription range for a dataset your account has access to. The API treats this as a parameter issue and will return a message such as "The date value ’2020-01-02’ is outside of the allowed range for this account".
• Solution: Verify your allowed date range by querying the GET /api/v1/account/my/data-access-rules endpoint to ensure your requested trade_date falls within your subscription bounds.
• Out-of-Bounds Limits: Providing a limit parameter that exceeds the maximum threshold (e.g., requesting more than 100,000 records).
• Solution: Cap your limit value and use the offset parameter to implement pagination.
• Malformed Dates or Types: Passing an incorrectly formatted date string for trade_date (e.g., not using standard YYYY-MM-DD) or passing letters into integer fields.
• Solution: Ensure all dynamic parameters conform strictly to the endpoint schemas defined in the documentation.
• Unsupported Filter Operations: Using invalid mathematical operators or syntax in your advanced filtering strings.
• Solution: Review the Advanced Filtering Guide and ensure operators like .gt, .lt, or .eq are used correctly based on the column's data type.

Handling: Client applications should parse the detail array natively to log specific, field-level errors. Your system should trigger a graceful degradation, halting execution and logging the output rather than attempting blind retries, as the request parameters are inherently malformed.

401 Unauthorized: Authentication#

Because the API delivers high-fidelity, institutional-grade market data, access is strictly controlled. A 401 Unauthorized status code indicates that the request lacks valid authentication credentials.

Missing API Key#

Error Response:

{
  "detail": "Not authenticated"
}

Meaning: The request did not include an API key.

Handling: Ensure that the API key is passed correctly in the X-API-KEY security header for all HTTP requests to the API.

Invalid API Key#

Error Response:

{
  "detail": "Invalid API key"
}

Meaning: The provided API key is incorrect, revoked, or formatted improperly.

Handling: Verify the key in your algoseek account dashboard. If the key was typed incorrectly, correct it in your application's environment variables.

403 Forbidden: Authorization#

A 403 Forbidden status code indicates that the request was understood, but the server is refusing to fulfill it due to authorization constraints.

IP Address Not Allowed#

Error Response:

{
  "detail": "Forbidden: IP address not allowed"
}

Meaning: The API key is valid, but the request originated from an IP address not listed in your identity's allowed subnets.

Handling: Quants and data engineering teams must ensure that the outbound IP addresses of their production servers, research environments, or VPNs are explicitly whitelisted via CIDR notation within the algoseek platform.

Dataset Access Forbidden#

Error Response:

{
  "detail": "This identity does not have access to dataset {dataset_id}"
}

Meaning: You have successfully authenticated, but your identity does not have the subscription or permissions required to access the specific dataset requested.

Handling: Review your data access rules via the GET /api/v1/account/my/data-access-rules endpoint. Contact your algoseek account representative to provision access to the required quantitative datasets.

404 Not Found: Resource Errors#

Error Response:

{
  "detail": "A dataset with the id '{dataset_id}' is not found"
}

Meaning: The requested dataset identifier does not exist in the algoseek metadata registry, the specific resource path is invalid, or you do not have the entitlements to view the requested dataset.

Handling: Query the GET /api/v1/meta/datasets endpoint to retrieve a list of valid dataset text identifiers before constructing dynamic resource paths in your data pipelines. If the dataset exists but you receive a 404, verify your subscriptions.

409 Conflict: Configuration Ceilings#

Error Response:

{
  "detail": "An account cannot have more than {max_active_api_keys} active API keys"
}

Meaning: The request conflicts with the current state of the server because you have reached the maximum allowed active API keys.

Handling: You will need to delete or deactivate an existing API key through the dashboard before creating a new one.

410 Gone: Resource Unavailable#

Error Response:

{
  "detail": "The account is deactivated" 
}

or

{
  "detail": "The API key access has expired"
}

Meaning: The resource or account you are trying to use is no longer available.

Handling: If your API key has expired, generate a new one. If your account is deactivated, please contact your account representative to restore access for your institutional operations.

429 Too Many Requests: Usage Quotas#

Error Response:

{
  "detail": "Monthly request limit exceeded: {used}/{limit} requests."
}

Meaning: Your account has exhausted its allocated quota limits. Quotas are enforced for both the number of requests and the volume of data scanned, on either a per-minute or per-month basis.

Handling:

• Pre-flight Checks: Before launching large historical backtesting tasks, programmatically check your current usage using the GET /api/v1/account/my/quotas endpoint.
• Throttling & Backoff: Implement exponential backoff and rate-limiting logic on your client to avoid hitting per-minute thresholds. Monthly limits will block requests until the billing cycle resets, so optimize queries to scan only necessary data.

503 Service Unavailable: Server Overload/Maintenance#

Error Response:

{
  "detail": "Service unavailable"
}

Meaning: The algoseek API is temporarily unable to handle the request. This is typically due to scheduled maintenance, temporary outages, or an unexpected backend overload.

Handling: Implement exponential backoff and retry logic in your client applications to gracefully re-attempt the connection after a short delay.

504 Gateway Timeout: Query Too Large#

Error Response:

{
  "detail": "Gateway timeout"
}

Meaning: The server acting as a gateway did not receive a response from the upstream server in time. This usually occurs when a requested query is too heavy or spans too large of a dataset slice to be processed within the allowed timeout window.

Handling: Optimize your query to reduce the computational load. Decrease your limit, narrow down the date range, or specify a smaller subset of columns rather than requesting all fields at once.

Best Practices#

To maintain uninterrupted access to historical market data and ensure robust algorithmic trading infrastructure, hedge funds and institutional clients should implement the following strategies:

1. Dynamic Quota Monitoring: Integrate the GET /api/v1/account/my/quotas endpoint into your monitoring dashboards. Set up automated alerts for when monthly usage reaches 80% or 90% of the limit.
2. Graceful Degradation: When encountering a 422 Validation Error, halt execution immediately rather than attempting blind retries.
3. Structured Logging: Parse the detail array natively in your data ingestion pipelines to capture exact failure states. This ensures that quants are not left debugging opaque "API failed" errors when running complex quantitative analysis.

Algoseek Datasets API: Error Handling Summary#

For your convenience, the following table summarizes the errors you may encounter when using the algoseek Datasets API: