> ## Documentation Index > Fetch the complete documentation index at: https://docs.orbitsearch.com/llms.txt > Use this file to discover all available pages before exploring further. # Handle Orbit Search API errors in your application > Understand the Orbit Search error response format and every error code your application may encounter, including HTTP status, cause, and remediation. Every error from the Orbit Search API follows a consistent JSON shape with a machine-readable `code` field. Building your error handling around these codes — rather than HTTP status codes or message strings — gives you reliable, forward-compatible error detection. This page covers the full error format and every code grouped by category. ## Error response format All error responses use this shape: ```json theme={"dark"} { "status": "failed", "error": { "code": "ERROR_CODE", "message": "Human-readable description of the error." } } ``` Some error codes include additional fields alongside `code` and `message`. For example, a credit-insufficient error also returns the amounts involved: ```json theme={"dark"} { "status": "failed", "error": { "code": "developer_api_credits_insufficient", "message": "Developer API credits are insufficient for this request", "requiredCredits": 2, "remainingCredits": 0 } } ``` Your error handling should always read the `error.code` field to determine what happened and how to respond. ## Error codes by category These errors indicate a problem with how the request is authenticated. Check your `Authorization` header and key configuration. | HTTP | Code | Description | | ---- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 401 | `missing_api_key` | No `Authorization: Bearer sk_orb_...` header was provided. Add the header with a valid developer API key. | | 403 | `invalid_api_key` | The key is malformed, revoked, expired, or unknown. Verify the key is active in your key list and has not been revoked or expired. | | 403 | `missing_api_key_scope` | The key does not include the scope required for this endpoint. For search, profile query, and Deep Search, the key needs `search:read`; for profile reads, it needs `profile:read`. Issue a replacement key with the correct scopes in the dashboard. | | 403 | `api_key_management_requires_user_auth` | A developer API key attempted to create, list, revoke, or delete keys. Manage keys in the Orbit developer dashboard instead. | Example handling: ```javascript theme={"dark"} if (error.code === "invalid_api_key") { // Key was revoked or expired — trigger key rotation flow await rotateApiKey(); } else if (error.code === "missing_api_key_scope") { // Log a configuration error — this needs a human to fix logger.error("API key missing required scope", { code: error.code }); } ``` These errors are returned with HTTP `400` when the search request body fails validation. Fix the request body before retrying — retrying with the same body will produce the same error. | Code | Description | | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `developer_query_required` | The `query` field is missing or empty. Provide a non-empty string. | | `developer_num_users_required` | The `numUsers` field is missing or not a positive integer. Provide a valid positive integer. | | `developer_num_users_limit_exceeded` | `numUsers` exceeds the maximum of 100. Reduce the value to 100 or below. | | `developer_user_id_override_forbidden` | The request body includes a `userId` field, which is not permitted for developer API key requests. Remove the field. | | `developer_search_replay_unsupported` | The request body includes a `searchId` field. Search replay is not supported for developer API key requests. Remove the field. | | `developer_profile_query_required` | Profile Query is missing a non-empty `query`. | | `developer_profile_query_too_long` | Profile Query received a `query` longer than 1,000 characters. | | `developer_profile_query_limit_invalid` | Profile Query received a `limit` that is not a positive integer. | | `developer_profile_query_limit_exceeded` | Profile Query received a `limit` greater than 50. | | `developer_deep_search_field_unsupported` | Deep Search received a top-level body field other than `requestId`, `runShape`, `profileId`, `email`, `phoneNumber`, `linkedinUrl`, `urls`, `usernames`, or `structuredIntent`. Legacy fields (`mode`, `partialProfile`, `dry_run`, `options`, `profile_id`, `orbit_id`) are flagged with a replacement hint. | | `developer_deep_search_input_required` | Deep Search did not receive an identity signal (`profileId`, `structuredIntent`, `email`, `phoneNumber`, `linkedinUrl`, `urls`, or `usernames`). | | `developer_deep_search_email_invalid` | Deep Search received a malformed `email`. | | `developer_deep_search_phone_invalid` | Deep Search received a malformed `phoneNumber`. | | `developer_deep_search_linkedin_invalid` | Deep Search received a malformed `linkedinUrl` or a non-profile LinkedIn URL. | | `developer_deep_search_field_invalid` | Deep Search received a `urls` or `usernames` value that is not an array of strings. | | `developer_deep_search_url_invalid` | Deep Search received a `urls` entry that is not a valid `http(s)` URL. | | `developer_deep_search_run_shape_invalid` | Deep Search received a `runShape` other than `partial_only`, `partial_plus_full`, `full_generation_only`, or `candidate_discovery`. | | `developer_deep_search_request_id_invalid` | Deep Search received a `requestId` that is not a non-empty string. | | `developer_deep_search_profile_id_invalid` | Deep Search received a `profileId` that is not a non-empty string. | | `developer_deep_search_personalization_unsupported` | Deep Search received `structuredIntent.personalization`, which requires synchronous search user context. | | `developer_deep_search_unprocessable_seed` | The provided Deep Search identity signals could not start a run. | | `structured_intent_required` | `structuredIntent` was provided but its value is not a valid object. | | `structured_intent_invalid` | `structuredIntent` is malformed or contains unsupported values. | | `structured_intent_version_unsupported` | `structuredIntent.version` must be `"v1"`. | | `structured_intent_entity_clauses_unsupported` | `entityClauses` are not part of the public structured DSL. | | `structured_intent_server_owned_field` | The request includes a server-owned structured intent field. | Example handling: ```javascript theme={"dark"} const VALIDATION_ERRORS = new Set([ "developer_query_required", "developer_num_users_required", "developer_num_users_limit_exceeded", "developer_user_id_override_forbidden", "developer_search_replay_unsupported", "developer_profile_query_required", "developer_profile_query_too_long", "developer_profile_query_limit_invalid", "developer_profile_query_limit_exceeded", "developer_deep_search_field_unsupported", "developer_deep_search_input_required", "developer_deep_search_email_invalid", "developer_deep_search_phone_invalid", "developer_deep_search_linkedin_invalid", "developer_deep_search_field_invalid", "developer_deep_search_url_invalid", "developer_deep_search_run_shape_invalid", "developer_deep_search_request_id_invalid", "developer_deep_search_personalization_unsupported", "developer_deep_search_unprocessable_seed", "structured_intent_required", "structured_intent_invalid", "structured_intent_version_unsupported", "structured_intent_entity_clauses_unsupported", "structured_intent_server_owned_field", ]); if (VALIDATION_ERRORS.has(error.code)) { // Do not retry — fix the request body throw new Error(`Invalid search request: ${error.code}`); } ``` These errors relate to organization API key requirements, directory access, and directory search scoping. | HTTP | Code | Description | | ---- | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 403 | `developer_api_key_organization_required` | The requested operation requires an organization API key. Personal API keys are rejected for directory scopes. Switch to an organization API key. | | 403 | `developer_api_key_organization_forbidden` | The organization API key is not authorized for the requested organization search scope. Ensure the key belongs to the correct organization. | | 404 | `search_directory_not_found` | One or more requested directories do not exist, have been archived, or are unavailable for search. Verify the `directoryId` values and check that the directories are active. | | 400 | `search_directory_cross_org_scope_unsupported` | A multi-directory search (`"type": "directories"`) included directories from more than one organization. All directories in a single request must belong to the same organization. | | 403 | `search_directory_access_api_key_forbidden` | The organization API key does not have a matching directory grant with `search` or `manage` permission. Add a grant for this key or use a key that already has access. | Directory access validation runs **before** credits are charged. If your key lacks a directory grant, no credits are consumed on the rejected request. Example handling: ```javascript theme={"dark"} if (error.code === "search_directory_not_found") { // Directory was archived or deleted — check directory list const directories = await listDirectories(organizationId); logger.warn("Directory not found", { directoryId, directories }); } else if (error.code === "search_directory_access_api_key_forbidden") { // Key lacks a grant — needs an admin to add one logger.error("API key lacks directory grant", { code: error.code }); } ``` These errors indicate you have hit a spending or throughput limit. They are separate from one another — a request can fail with `429` even when credits remain, and a request can fail with `402` even when the rate limit has capacity. | HTTP | Code | Description | | ---- | ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 402 | `developer_api_credits_insufficient` | Your remaining credits are lower than the cost of the requested operation (2 credits for Search, 1 for Profile Query or profile reads, 10 for Deep Search by default). The response includes `requiredCredits` and `remainingCredits`. Top up your credit balance before retrying. | | 429 | `developer_api_key_rate_limited` | The per-key rate limit has been exceeded. Search and Profile Query default to 25 requests per second with bursts up to 100 requests. Profile reads default to 50 requests per second with bursts up to 250 requests. Deep Search start requests default to 5 requests per second with bursts up to 25 requests; Deep Search status polling has its own bucket at 25 requests per second with bursts up to 150 requests. Back off and retry after the bucket refills. | Credit-insufficient response example: ```json theme={"dark"} { "status": "failed", "error": { "code": "developer_api_credits_insufficient", "message": "Developer API credits are insufficient for this request", "requiredCredits": 2, "remainingCredits": 0 } } ``` Example handling: ```javascript theme={"dark"} if (error.code === "developer_api_key_rate_limited") { // Exponential backoff await sleep(backoffMs); return retry(request); } if (error.code === "developer_api_credits_insufficient") { const { requiredCredits, remainingCredits } = error; logger.warn("Insufficient credits", { requiredCredits, remainingCredits }); // Notify operators or pause non-essential requests } ``` Check the `X-Developer-API-Credits-Remaining` response header after each successful request to track your balance proactively. This lets you alert before you hit zero rather than discovering the problem at request time. These errors are returned with HTTP `409` when there is a conflict with a previously submitted `Idempotency-Key` header value. | Code | Description | | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `developer_api_idempotency_key_conflict` | You reused an idempotency key with different request parameters. Each unique idempotency key is permanently bound to the parameters of the first request that used it. Generate a new key for this request. | | `developer_api_idempotency_key_refunded` | The idempotency key belongs to a request that was refunded (for example, an empty-result search). You cannot reuse a refunded key for a new charge. Generate a new idempotency key and retry. | Example handling: ```javascript theme={"dark"} if (error.code === "developer_api_idempotency_key_conflict") { // Bug in your code — you're reusing a key with different params throw new Error("Idempotency key reused with different parameters"); } if (error.code === "developer_api_idempotency_key_refunded") { // Safe to retry — just generate a fresh key return retry({ ...request, idempotencyKey: crypto.randomUUID() }); } ``` These errors are specific to `POST /v2/developer/deep-search` and `GET /v2/developer/deep-search/:requestId`. | HTTP | Code | Description | | ---- | --------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `developer_deep_search_field_unsupported` | The body includes a top-level field other than `requestId`, `runShape`, `profileId`, `email`, `phoneNumber`, `linkedinUrl`, `urls`, `usernames`, or `structuredIntent`. Legacy fields (`mode`, `partialProfile`, `dry_run`, `options`, `profile_id`, `orbit_id`) are flagged with a replacement hint. | | 400 | `developer_deep_search_input_required` | The body is missing an identity signal (`profileId`, `structuredIntent`, `email`, `phoneNumber`, `linkedinUrl`, `urls`, or `usernames`). | | 400 | `developer_deep_search_email_invalid` | `email` is malformed. | | 400 | `developer_deep_search_phone_invalid` | `phoneNumber` is malformed. | | 400 | `developer_deep_search_linkedin_invalid` | `linkedinUrl` is malformed or is not a LinkedIn profile URL. | | 400 | `developer_deep_search_field_invalid` | `urls` or `usernames` is not an array of strings. | | 400 | `developer_deep_search_url_invalid` | `urls` contains a value that is not a valid `http(s)` URL. | | 400 | `developer_deep_search_run_shape_invalid` | `runShape` is not one of `partial_only`, `partial_plus_full`, `full_generation_only`, `candidate_discovery`. | | 400 | `developer_deep_search_request_id_invalid` | `requestId` is not a non-empty string. | | 400 | `developer_deep_search_profile_id_invalid` | `profileId` is not a non-empty string. | | 400 | `developer_deep_search_personalization_unsupported` | The structured intent includes personalization, which requires synchronous search user context. | | 400 | `developer_deep_search_unprocessable_seed` | The provided identity signals could not start a Deep Search run. | | 400 | `developer_deep_search_invalid_request` | The request body was rejected; the message describes what to fix. | | 400 | `structured_intent_required` | `structuredIntent` was provided but its value is not a valid object. | | 404 | `developer_deep_search_run_not_found` | The `requestId` does not match a known Deep Search run. | | 502 | `developer_deep_search_request_failed` | Deep Search did not accept the request or could not be reached. Retry later. | | 503 | `developer_deep_search_unavailable_for_request` | Deep Search is not available for this request. | | 503 | `developer_deep_search_unavailable` | Deep Search is currently unavailable. Retry later. | | 503 | `developer_deep_search_not_configured` | Deep Search is not configured in this environment. | Deep Search idempotency is handled by the `requestId` body field, not the `Idempotency-Key` header. Re-sending the same `requestId` returns `200` with `status: "already_running"` instead of a conflict error. | HTTP | Code | Description | | ---- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 404 | `developer_profile_not_found` | The profile ID does not resolve to a public Orbit profile. The profile may have been removed, made private, or the ID may be incorrect. Profile reads and Profile Query requests that return this error are automatically refunded. | Example handling: ```javascript theme={"dark"} if (error.code === "developer_profile_not_found") { // No credits were consumed — safe to skip or log logger.info("Profile not found, skipping", { profileId }); } ``` ## HTTP status code summary | Status | Codes | | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 400 | `developer_query_required`, `developer_num_users_required`, `developer_num_users_limit_exceeded`, `developer_user_id_override_forbidden`, `developer_search_replay_unsupported`, `developer_profile_query_required`, `developer_profile_query_too_long`, `developer_profile_query_limit_invalid`, `developer_profile_query_limit_exceeded`, `structured_intent_required`, `structured_intent_invalid`, `structured_intent_version_unsupported`, `structured_intent_entity_clauses_unsupported`, `structured_intent_server_owned_field`, `search_directory_cross_org_scope_unsupported`, `developer_deep_search_field_unsupported`, `developer_deep_search_field_invalid`, `developer_deep_search_url_invalid`, `developer_deep_search_input_required`, `developer_deep_search_email_invalid`, `developer_deep_search_phone_invalid`, `developer_deep_search_linkedin_invalid`, `developer_deep_search_run_shape_invalid`, `developer_deep_search_request_id_invalid`, `developer_deep_search_personalization_unsupported`, `developer_deep_search_unprocessable_seed`, `developer_deep_search_invalid_request` | | 401 | `missing_api_key` | | 402 | `developer_api_credits_insufficient` | | 403 | `invalid_api_key`, `missing_api_key_scope`, `api_key_management_requires_user_auth`, `developer_api_key_organization_required`, `developer_api_key_organization_forbidden`, `search_directory_access_api_key_forbidden` | | 404 | `developer_profile_not_found`, `search_directory_not_found`, `developer_deep_search_run_not_found` | | 409 | `developer_api_idempotency_key_conflict`, `developer_api_idempotency_key_refunded` | | 429 | `developer_api_key_rate_limited` | | 502 | `developer_deep_search_request_failed` | | 503 | `developer_deep_search_unavailable_for_request`, `developer_deep_search_unavailable`, `developer_deep_search_not_configured` |