Error Reference¶

Error Response Format¶

All API errors return a consistent JSON envelope. The error object always includes a machine-readable code and a human-readable message. Some errors include a details object with field-level information.

{
  "error": {
    "code": "invalid_request",
    "message": "dataset_id is required",
    "details": {
      "field": "dataset_id"
    }
  },
  "request_id": "req_abc123",
  "timestamp": "2026-03-27T12:00:00Z"
}

Every error response includes a request_id for tracing and a timestamp in ISO 8601 UTC. Include the request_id when contacting support.

HTTP Status Codes¶

Status Code	Meaning	When Returned
`200 OK`	Request succeeded	Reads and synchronous mutations
`201 Created`	Resource created	Successful `POST` that creates a resource
`202 Accepted`	Async work enqueued	Operations that only enqueue a job
`204 No Content`	Success, no body	Deletions and actions with no response body
`400 Bad Request`	Malformed input	Missing required fields, invalid JSON, bad parameter types
`401 Unauthorized`	Authentication failed	Missing, expired, or invalid `Authorization` header
`403 Forbidden`	Insufficient permissions	Valid credentials but missing required scope or tenant access
`404 Not Found`	Resource does not exist	Invalid resource ID or resource not accessible to the caller
`409 Conflict`	State or idempotency conflict	Duplicate `Idempotency-Key` with different body, or conflicting state transition
`429 Too Many Requests`	Rate limit exceeded	Too many requests in the current window
`500 Internal Server Error`	Server error	Unexpected server-side failure
`503 Service Unavailable`	Temporarily unavailable	Planned maintenance or transient overload

Error Codes Reference¶

Error Code	HTTP Status	Description	Resolution
`bad_request`	400	The request body is malformed, missing required fields, or contains invalid parameter types.	Check the `details.field` value in the response. Verify that all required fields are present and correctly typed. Refer to the API contract for the endpoint schema.
`unauthorized`	401	The `Authorization` header is missing, the token is expired, or the credential is invalid.	Verify that your request includes a valid `Authorization: Bearer <token>` header. If using a session token, re-authenticate. If using an API key, confirm it has not been revoked.
`forbidden`	403	The authenticated principal does not have the required scope or tenant-level permission for this action.	Check the scopes assigned to your API key or user role. Ensure the key has the required scope (e.g., `search:query` for search, `datasets:write` for dataset creation). Use `GET /v1/me` to inspect your current scopes.
`not_found`	404	The requested resource does not exist or is not accessible to the authenticated tenant.	Verify the resource ID is correct. Confirm that the resource belongs to your tenant or is a marketplace resource you have access to. Deleted resources also return `404`.
`conflict`	409	A resource with the same identity already exists, or an `Idempotency-Key` was reused with a different request body.	For idempotency conflicts, ensure you send the same request body with the same `Idempotency-Key`. For state conflicts, check the current resource state before retrying the operation.
`rate_limited`	429	The request was rejected because the caller exceeded the allowed request rate.	Wait for the duration indicated in the `Retry-After` response header before retrying. Implement exponential backoff in your client. Consider reducing request frequency or batching operations.
`internal_error`	500	An unexpected server-side error occurred.	Retry the request with exponential backoff. If the error persists, contact support with the `request_id` from the error response. Do not retry non-idempotent requests without an `Idempotency-Key`.

Common Error Scenarios¶

Upload URL Expired¶

Symptom: Your PUT to the presigned upload URL returns 403 Forbidden or 400 Bad Request from the storage backend.

Cause: Presigned upload URLs expire after 15 minutes. If your upload did not complete within that window, the URL is no longer valid.

Resolution: Call POST /v1/uploads again to obtain a fresh upload URL. For large files, use multipart upload (automatically triggered above 64 MiB) to upload in smaller parts within the TTL. Each part gets its own presigned URL.

API Key Missing Required Scope¶

Symptom: 403 forbidden with a message indicating insufficient scope.

Cause: The API key used for the request does not include the scope required by the endpoint. For example, calling POST /v1/search with a key that only has datasets:read but not search:query.

Resolution: Create a new API key with the required scopes via POST /v1/api-keys, or update the existing key's role if your tenant permissions allow it. Common scope assignments: search:query for search, objects:write for uploads, billing:read for spend reports.

Symptom: 400 bad_request when calling POST /v1/auth/signup.

Cause: The password field in the signup request body does not meet the minimum length requirement.

Resolution: Ensure the password meets the platform's minimum length and complexity requirements. Retry the signup request with a stronger password. The error details will indicate the password field as the source.

Dataset Not Found After Deletion¶

Symptom: 404 not_found when accessing a dataset that previously existed.

Cause: The dataset has transitioned to pending_deletion or deleted status. Once a dataset enters deletion, it is no longer accessible via the API. Its objects are tombstoned and removed from search indexes.

Resolution: Deleted datasets cannot be recovered. If deletion was unintentional, contact support immediately with the dataset_id and request_id from the delete operation. Audit logs record all deletion events for traceability.

Idempotency Key Conflict¶

Symptom: 409 conflict when retrying a POST request.

Cause: The Idempotency-Key header was reused with a request body that differs from the original request. The server detected the mismatch and rejected the retry.

Resolution: Use a unique Idempotency-Key for each distinct operation. If retrying a failed request, ensure the request body is identical to the original. If the original request succeeded, the server returns the original response for matching retries.