Skip to main content
The OrbiSearch API uses standard HTTP status codes to indicate whether a request succeeded or failed. Successful requests return 200 OK. Errors return a JSON body with a detail field that describes what went wrong.

​
HTTP status codes

CodeStatusWhen it’s returned
200OKRequest succeeded.
400Bad RequestRequest body or path parameter is malformed (e.g. empty email list, invalid job_id format, more than 100,000 emails in a bulk submission).
401UnauthorizedX-API-Key header is missing or contains an invalid key.
403ForbiddenInsufficient credit balance for the requested operation.
404Not FoundThe requested job_id does not exist or does not belong to your API key.
409ConflictBulk job results requested before the job has reached complete.
422Unprocessable EntityQuery, path, or body parameter failed type validation.
429Too Many RequestsRate limit exceeded.
500Internal Server ErrorAn unexpected server error occurred. Rare; typically transient.
502Bad GatewayThe downstream verification service is temporarily unavailable.
All error responses share the same shape: 
{
  "detail": "A human-readable description of what went wrong."
}

​
400 Bad Request

Returned when the request is structurally valid but semantically rejected. Common causes:
  • Empty emails array on POST /v1/bulk
  • More than 100,000 entries in emails
  • A path-level job_id that isn’t a valid UUID
400
{
  "detail": "Email list cannot be empty"
}
How to fix: Inspect the detail message — it identifies the offending field. For job_id errors, confirm you’re passing the UUID returned by POST /v1/bulk.

​
401 Unauthorized

Returned when the X-API-Key header is missing or contains an invalid key.
401
{
  "detail": "API key required in X-API-Key header"
}
How to fix: Make sure every request includes the X-API-Key header with a valid API key. The header name is case-sensitive.
cURL
curl --request GET \
  --url "https://api.orbisearch.com/v1/verify?email=jane.doe%40acme.com" \
  --header "X-API-Key: YOUR_API_KEY"

​
403 Forbidden — insufficient credits

Returned when your credit balance is too low for the requested operation. Single verifications cost 0.2 credits; bulk submissions are pre-charged for the full deduplicated cost. The error body tells you both your current balance and what was required.
403
{
  "detail": "Insufficient credits. You have 0.15 credits but need 0.2."
}
How to fix: Top up your balance from the dashboard, then retry. You can check your current balance at any time via GET /v1/credits.

​
404 Not Found

Returned when a job_id doesn’t exist, or exists but belongs to a different API key.
404
{
  "detail": "Job not found"
}
How to fix: Confirm you’re using the job_id from the original POST /v1/bulk response and that you’re authenticating with the same API key that created the job.

​
409 Conflict — job not ready

Returned by GET /v1/bulk/{job_id}/results when the job hasn’t finished yet. The detail includes the job’s current status.
409
{
  "detail": "Job is not completed yet. Current status: in_progress"
}
How to fix: Poll GET /v1/bulk/{job_id} until status is complete (or partial_complete_retrying if you want partial results) before fetching results. Partial results can also be fetched directly — see bulk results for partial-fetch behaviour.

​
422 Unprocessable Entity — validation errors

Returned when a query, path, or body parameter fails type validation (e.g. email is missing, timeout is outside the 3–90 range, request body isn’t valid JSON).
422
{
  "detail": "Missing required query parameter: email"
}
How to fix: The detail string identifies the offending parameter and the validation rule it violated. Common cases: missing required field, value outside allowed range, wrong type.

​
429 Too Many Requests

Returned when you exceed the rate limit of 20 requests per second per API key across the entire /v1/* API. The response includes a Retry-After header indicating how many seconds to wait before retrying.
429
{
  "detail": "Rate limit exceeded. Maximum 20 requests per second per API key. Contact us to discuss higher limits."
}
Response headers: 
Retry-After: 1
How to fix: Honour the Retry-After value (currently always 1, may grow in future) and back off before retrying. For sustained high throughput, use the POST /v1/bulk endpoint instead — it’s designed for large-volume workloads and isn’t subject to the per-second cap. Contact us if you need a higher single-verification rate.

​
500 Internal Server Error

Returned when an unexpected server-side error occurs. These are rare and typically transient. How to fix: Wait a moment and retry the request. If the error persists, contact OrbiSearch support with the request details and timestamp. Credits deducted before the error are automatically refunded.

​
502 Bad Gateway

Returned when the downstream email verification service is temporarily unavailable.
502
{
  "detail": "Email verification service temporarily unavailable"
}
How to fix: Retry with exponential backoff. Credits deducted before the error are automatically refunded. If the issue persists for more than a few minutes, check our status page or contact support.

​
Common errors and fixes

ErrorCauseFix
API key required in X-API-Key headerMissing X-API-Key headerAdd --header "X-API-Key: YOUR_API_KEY" to every request
Insufficient credits...Balance below required costTop up your balance and retry
Email list cannot be emptyPOST /v1/bulk with empty emails arrayInclude at least one address
Maximum 100,000 emails per batchBulk submission too largeSplit into multiple jobs of ≤100,000 each
Invalid job ID formatjob_id is not a valid UUIDUse the job_id returned by POST /v1/bulk verbatim
Job not foundjob_id doesn’t exist or belongs to another API keyConfirm the job ID and authenticate with the original API key
Job is not completed yet...Fetched results before the job reached completePoll job status or accept the partial result set
Rate limit exceeded...More than 20 requests per secondHonour Retry-After; use /v1/bulk for high volume