Errors

Ocean.io uses standard HTTP status codes. All error responses return a JSON body with a detail field.

Status code reference#

Code Name Meaning
200 OK Request succeeded
201 Created Processing started asynchronously — results will arrive via webhook, or retry in a few minutes
400 Bad Request Malformed JSON, or API token provided in both header and query param
401 Unauthorized API token is missing or not recognised
402 Payment Required Insufficient credits to complete the request
403 Forbidden Token does not have permission for this operation
404 Not Found The resource (company or person) could not be found in the database
422 Unprocessable Entity Request body failed schema validation — check the detail array for field-level errors
429 Too Many Requests Rate limit exceeded — see Rate Limiting
5xx Server Error Something went wrong on our end — try again after a short delay

Error response format#

Simple errors (400, 401, 402, 403, 404):

{
  "detail": "Insufficient credits"
}

Validation errors (422):

{
  "detail": [
    {
      "loc": ["body", "companiesFilters", "companySizes", 0],
      "msg": "'XL' is not a valid company size",
      "type": "value_error.enum",
      "input": "XL",
      "ctx": { "enum_values": ["0-1", "2-10", "11-50", "51-200", "201-500"] }
    }
  ]
}

Each item in the detail array contains:

Field Description
loc Path to the field that caused the error (e.g., ["body", "companiesFilters", "companySizes", 0])
msg Human-readable description of the error
type Machine-readable error type
input The value that was rejected
ctx What values are allowed (e.g. {"enum_values": ["0-1", "2-10", ...]})

Common mistakes#

Symptom Likely cause Fix
400 on every request Token provided in both header and query param Use only one method
401 with valid-looking token Token has been revoked Regenerate token in Account Settings
402 immediately Credit balance exhausted Top up credits or check recurrent renewal date
422 on filter values Invalid enum value (e.g., wrong industry name) Fetch valid values from /v2/data-fields
422 on location filters Wrong ISO country code format Use lowercase alpha-2 codes, e.g. "de" not "DE" or "Germany"
Results return 0 but no error Filters are too narrow Try relaxing minScore, removing filters one at a time
201 instead of 200 on Enrich Domain not yet in database Wait 2–5 minutes and retry — background crawling was triggered

What's next?#