In addition to HTTP status codes, the API may return error codes in the response body.
These codes provide more granular information about what went wrong, even when the HTTP response itself is successful (2xx).
Clients should inspect the response body for these codes to correctly handle errors programmatically.
| Code | Description |
|---|---|
| dataset_limit_exceeded | The dataset is at or above the maximum allowed size. |
| duplicate_record | Resource already exists or violates the uniqueness constraint. |
| forbidden | Authenticated but not allowed to perform the action. |
| internal_error | Unhandled server error. |
| invalid_api_key | The API key provided is incorrect or expired. |
| invalid_field_value | Field present, but value is invalid or out of bounds. |
| invalid_json | Malformed or non-parseable JSON. |
| invalid_input | Generic invalid data or format. |
| method_not_allowed | HTTP method is not allowed on this endpoint. |
| missing_required_field | A required parameter or field was omitted. |
| not_found | The requested resource doesn't exist. |
| processing_failed | Data ingestion accepted, but internal processing failed. |
| rate_limited | Request rejected due to exceeding rate limits. |
| request_too_large | Body/payload exceeds allowed size. |
| schema_mismatch | Data doesn't match the expected schema or types. |
| service_unavailable | Temporary outage or maintenance. |
| too_many_errors | The request failed due to excessive per-record errors. |
| unsupported_media_type | Content type not supported (e.g., not JSON). |
- Check the
codefield to implement programmatic handling. - Validate inputs before submitting to avoid
invalid_inputorinvalid_field_value. - Handle rate limits (
rate_limited) with retries and exponential backoff. - Expect schema evolution and handle
schema_mismatcherrors gracefully. - Log and alert on
internal_errororservice_unavailablefor visibility.