## Error catalog

Every error has this shape: `{"error": {"code", "message", "param"?, "hint"?, "retryable", "doc_url", "details"?}}`. One HTTP status per code.

| Status | Code | Meaning | What to do | Retry |
| --- | --- | --- | --- | --- |
| 400 | `COLUMN_NAME_CONFLICT` | Two aggregate columns would have the same name. | Give one of the metrics an explicit `as` name. | no |
| 400 | `CURSOR_INVALID` | The cursor is malformed, belongs to another query or another account. | Send the cursor exactly as returned, with the same API key, or start again without a cursor. | no |
| 400 | `OPERATOR_NOT_SUPPORTED` | The operator is not available for this field. | Use one of the operators listed for the field in /schema. | no |
| 400 | `QUERY_TOO_COMPLEX` | The filter exceeds the complexity limits. | Stay within 3 nesting levels, 30 predicates and 100 values per array. | no |
| 400 | `SEMANTIC_NOT_SUPPORTED` | Semantic ranking (query / similar_to) is only available for startups. | Use a `text` match filter on other collections. | no |
| 400 | `TAG_ARRAY_NEEDS_OPERATOR` | A bare array was given for a tag field. | Say whether any or all values must match: {"any": [...]} or {"all": [...]}. | no |
| 400 | `UNKNOWN_FIELD` | A field name is not part of this collection. | Use a name from GET /schema/{collection}; `details.did_you_mean` lists close matches. | no |
| 400 | `VALIDATION_FAILED` | The request does not match the endpoint contract. | Correct the field named in `param` using `hint`. | no |
| 400 | `VALUE_AMBIGUOUS` | A friendly filter value matches several canonical values. | Pick one of `details.candidates`. | no |
| 400 | `VALUE_UNKNOWN` | A filter value does not match any known value. | Use a canonical value; `details.did_you_mean` lists close matches. | no |
| 401 | `UNAUTHORIZED` | The API key is missing, invalid or revoked. | Send `Authorization: Bearer ssk_live_…` with an active key from /account/api-keys. | no |
| 402 | `INSUFFICIENT_FUNDS` | The account balance cannot cover this request or job. | Top up the balance, then retry. | no |
| 403 | `FORBIDDEN` | This key or application may not perform the operation. | For OAuth apps, grant the permission on the StartupSeeker consent screen. | no |
| 403 | `SPEND_LIMIT_EXCEEDED` | A per-job or daily enrichment spend limit would be exceeded. | Reduce the job or wait until `details.resets_at`. | no |
| 404 | `NOT_FOUND` | The record or resource does not exist for this account. | Check the id or ref; resources are account-scoped. | no |
| 404 | `RECORD_REMOVED` | The record was suppressed or deleted. | Remove the ref from your system. | no |
| 405 | `METHOD_NOT_ALLOWED` | The endpoint exists but not with this HTTP method. | Use a method listed in the Allow header. | no |
| 409 | `CHECK_ONLY_JOB` | A check-only enrichment has nothing to approve or configure. | Read its results, or create a job without check_only. | no |
| 409 | `CONFLICT` | The resource changed concurrently or already exists. | Read the resource and retry the change. | no |
| 409 | `IDEMPOTENCY_IN_PROGRESS` | A request with this Idempotency-Key is still running. | Retry the identical request with the same key after `Retry-After`. | yes |
| 409 | `IDEMPOTENCY_MISMATCH` | This Idempotency-Key was already used with a different request. | Use a new key for a different request. | no |
| 409 | `JOB_NOT_CONFIGURABLE` | The job can no longer be reconfigured. | Only jobs awaiting approval can change; create a new job instead. | no |
| 409 | `PRICE_CHANGED` | The price rose since the quote was issued. | Review `details.quote` and approve its quote_id. | no |
| 409 | `QUOTE_EXPIRED` | The quote is older than 30 minutes or was replaced. | Approve the new quote in `details.quote` (or read the job for it). | no |
| 409 | `QUOTE_NOT_READY` | The job is still quoting. | Wait for status awaiting_approval (GET with ?wait=10). | yes |
| 409 | `REF_AMBIGUOUS` | The ref matches several records. | Use one of the UUIDs in `details.candidates`. | no |
| 410 | `CURSOR_EXPIRED` | The cursor expired (24 h, or 30 min for semantic rankings). | Run the query again without a cursor. | no |
| 410 | `SEARCH_EXPIRED` | The ranked search (search_id) expired after 30 minutes. | Run the semantic search again and use its new search_id. | no |
| 413 | `BODY_TOO_LARGE` | The request body exceeds 16 KB. | Send fewer values; split large inputs across requests. | no |
| 413 | `RECORD_TOO_LARGE` | A single record exceeds the 1 MB response budget. | Request fewer fields or expands. | no |
| 429 | `QUOTA_EXCEEDED` | A daily or concurrency quota is used up. | Wait until `details.resets_at`; see GET /account. | yes |
| 429 | `RATE_LIMITED` | Too many requests in the current window. | Wait for `Retry-After` seconds. | yes |
| 500 | `INTERNAL_ERROR` | An unexpected server error. | Retry once; contact support with the request id if it persists. | yes |
| 500 | `MUTATION_OUTCOME_UNKNOWN` | The change may or may not have been applied. | Retry with the same Idempotency-Key; never with a new key. Read the resource to reconcile. | yes |
| 503 | `SERVICE_UNAVAILABLE` | A dependency is temporarily unavailable. | Retry after `Retry-After` seconds. | yes |
| 504 | `QUERY_TIMEOUT` | The query ran out of its time budget. | Retry once; if it repeats, narrow the filter. | yes |