Skip to main content

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.

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: 
{
  "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: 
{
  "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.
HTTPCodeDescription
401missing_api_keyNo Authorization: Bearer sk_orb_... header was provided. Add the header with a valid developer API key.
403invalid_api_keyThe key is malformed, revoked, expired, or unknown. Verify the key is active in your key list and has not been revoked or expired.
403missing_api_key_scopeThe key does not include the scope required for this endpoint. For search, the key needs search:read; for profile reads, it needs profile:read. Issue a replacement key with the correct scopes in the dashboard.
403api_key_management_requires_user_authA developer API key attempted to create, list, revoke, or delete keys. Manage keys in the Orbit developer dashboard instead.
Example handling:
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.
CodeDescription
developer_query_requiredThe query field is missing or empty. Provide a non-empty string.
developer_num_users_requiredThe numUsers field is missing or not a positive integer. Provide a valid positive integer.
developer_num_users_limit_exceedednumUsers exceeds the maximum of 100. Reduce the value to 100 or below.
developer_user_id_override_forbiddenThe request body includes a userId field, which is not permitted for developer API key requests. Remove the field.
developer_search_replay_unsupportedThe request body includes a searchId field. Search replay is not supported for developer API key requests. Remove the field.
Example handling:
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",
]);

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.
HTTPCodeDescription
403developer_api_key_organization_requiredThe requested operation requires an organization API key. Personal API keys are rejected for directory scopes. Switch to an organization API key.
403developer_api_key_organization_forbiddenThe organization API key is not authorized for the requested organization search scope. Ensure the key belongs to the correct organization.
404search_directory_not_foundOne 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.
400search_directory_cross_org_scope_unsupportedA multi-directory search ("type": "directories") included directories from more than one organization. All directories in a single request must belong to the same organization.
403search_directory_access_api_key_forbiddenThe 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:
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.
HTTPCodeDescription
402developer_api_credits_insufficientYour remaining credits are lower than the cost of the requested operation (2 credits for search, 1 for profile reads by default). The response includes requiredCredits and remainingCredits. Top up your credit balance before retrying.
429developer_api_key_rate_limitedThe per-key rate limit has been exceeded. The default limit is 60 search requests per 60 seconds per API key (120 profile reads per 60 seconds). Back off and retry after the window resets.
Credit-insufficient response example:
{
  "status": "failed",
  "error": {
    "code": "developer_api_credits_insufficient",
    "message": "Developer API credits are insufficient for this request",
    "requiredCredits": 2,
    "remainingCredits": 0
  }
}
Example handling:
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.
CodeDescription
developer_api_idempotency_key_conflictYou 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_refundedThe 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:
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() });
}
HTTPCodeDescription
404developer_profile_not_foundThe 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 that return this error are automatically refunded.
Example handling:
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

StatusCodes
400developer_query_required, developer_num_users_required, developer_num_users_limit_exceeded, developer_user_id_override_forbidden, developer_search_replay_unsupported, search_directory_cross_org_scope_unsupported
401missing_api_key
402developer_api_credits_insufficient
403invalid_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
404developer_profile_not_found, search_directory_not_found
409developer_api_idempotency_key_conflict, developer_api_idempotency_key_refunded
429developer_api_key_rate_limited