# Error codes

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.

## Error codes reference

| 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). |


## Handling errors

- Check the `code` field to implement programmatic handling.
- Validate inputs before submitting to avoid `invalid_input` or `invalid_field_value`.
- Handle rate limits (`rate_limited`) with retries and exponential backoff.
- Expect schema evolution and handle `schema_mismatch` errors gracefully.
- Log and alert on `internal_error` or `service_unavailable` for visibility.