API Reference

Errors

Understand API errors and how to handle failed requests.

Overview

When a request cannot be completed, the API returns an HTTP error status together with a structured error response.

Use the HTTP status code for the broad category of the failure and the error code for more specific handling.

Client applications should generally handle 4xx responses as request or usage errors. Server-side 5xx errors are not documented here because they indicate an internal service failure.

Error Response

A typical API error response looks like this:

{
  "detail": {
    "code": "ERROR_CODE",
    "message": "A description of the error."
  }
}

The code identifies the error type, while message provides a human-readable description.

Common Errors

The following errors are the most relevant for client-side handling.

Status	Error code	Meaning
400	INVALID_CSV_FORMAT INVALID_DATASET MISSING_REQUIRED_COLUMNS ...	The request or supplied dataset data is invalid.
401	INVALID_OR_INACTIVE_API_KEY	The API key is invalid or inactive.
404	DATASET_NOT_FOUND	The requested dataset could not be found.
409	EMAIL_ALREADY_USED_FOR_TRIAL	The requested trial operation conflicts with an existing trial.
413	FILE_TOO_LARGE	The uploaded dataset exceeds the maximum file size allowed for the current plan.
422	INVALID_REQUEST	The request is missing a required field or does not satisfy the expected request schema.
429	RATE_LIMIT_EXCEEDED	The request rate limit was exceeded.
429	QUOTA_EXCEEDED	The available risk calculation quota has been exhausted.

For validation-related 400 responses, check the request data and dataset contents before retrying.

For 429 responses, wait and retry according to the relevant usage limit. Quota exhaustion requires waiting for the current plan period to renew or changing the current plan.