Errors

Errors come back as JSON, with a stable code to test in your code and a message to show or log:

{
  "error": {
    "code": "invalid_request",
    "message": "The request has invalid fields.",
    "details": [
      "Max results must be a whole number between 1 and 1000.",
      "Sort must be one of: relevance, date_asc, date_desc."
    ]
  }
}

details is there when there are several problems, one line each. Match on code, not on message: messages can be reworded.

An error never takes a request from your quota, nor a credit. When a search fails after it was counted, the request or the credits are given back before the answer is sent. One exception: when the search service did answer but brought nothing back — file_not_found, rejected, a source_error read from its reply, file_withheld — the search is free up to a daily allowance (see Limits); past it, it counts like any search. A service that is down, busy or too slow is always free, and so is an archive Orelys cannot check (archive_unchecked). X-Request-Charged always tells you.

Error codes

Your request

Status	Code	What happened	What to do
`400`	`invalid_request`	A field is missing, unknown or out of range.	Fix the fields listed in `details`.
`400`	`invalid_json`	The body is not valid JSON.	Check the body you send.
`400`	`rejected`	The search service refused the search.	Check the values; `details` may say why.
`400`	`key_in_url`	The API key was in the URL. A real key is revoked at once (`key_revoked: true`).	Create a new key and send it in a header (how).
`404`	`not_found`	No such route.	Check the path and the method.
`404`	`file_not_found`	No file matches this System ID or Storage ID.	Check the identifier (and the bucket).
`405`	`method_not_allowed`	Wrong method, e.g. `GET` on a search route.	Searches are `POST`; the rest is `GET`.
`413`	`payload_too_large`	The body is over 16 KB.	Send a smaller body.
`415`	`unsupported_media_type`	The body is not sent as JSON.	Add `Content-Type: application/json`.
`451`	`file_withheld`	The file or archive mentions a selector removed at its owner’s request. It is not delivered.	See Data removal.
`451`	`archive_unchecked`	The archive cannot be checked for removed selectors (encrypted, in a format Orelys cannot open, or too large once unpacked). It is not delivered.	See Data removal.

Your key and your plan

Status	Code	What happened	What to do
`401`	`missing_api_key`	No key sent.	Add `Authorization: Bearer <key>`.
`401`	`invalid_api_key`	Unknown key — mistyped, regenerated or revoked.	Use your current key, from orelys.io/account/api, or regenerate it there.
`403`	`plan_required`	The plan does not include the API.	Move to Professional or Enterprise.
`403`	`mode_not_in_plan`	The plan does not include this search mode.	Check `modes` in `/v1/me`.
`403`	`account_blocked`	The account is blocked.	Contact support.
`402`	`insufficient_credits`	The credit balance is lower than the cost of the OSINT search.	Credits are not on sale on the website yet: write to support@orelys.io.

Limits

Status	Code	What happened	What to do
`429`	`rate_limited`	Over your plan’s searches a minute: 60 on Professional, 120 on Enterprise.	Wait `Retry-After` seconds.
`429`	`concurrency_limited`	Already as many searches running as your plan allows: 3 on Professional, 5 on Enterprise.	Wait for one to finish.
`429`	`ip_rate_limited`	Over 120 calls in a minute from your address.	Wait `Retry-After` seconds.
`429`	`quota_exceeded`	The daily quota is used up.	Wait for the reset at 02:00 Paris time.

The search service

Status	Code	What happened	What to do
`502`	`source_error`	The search service returned an error.	Try again later.
`502`	`source_unreachable`	The search service could not be reached.	Try again later.
`502`	`response_too_large`	The result is too large to deliver.	Narrow the search, e.g. with `max_results`.
`503`	`service_unavailable`	Search is down for a moment.	Try again later; check the status page.
`503`	`source_busy`	The search service is busy.	Wait `Retry-After` seconds.
`504`	`source_timeout`	No answer within 30 seconds.	Try again, with a narrower search.
`502`	`sources_unavailable`	OSINT: not one source could be reached. Credits given back.	Try again later.
`503`	`module_unavailable`	OSINT: the module is down for a moment.	Try again later.
`500`	`internal_error`	Something broke on our side.	Try again; if it persists, send the `X-Request-Id` to support.

Get started

Essentials

Searching

Error codes

Your request

Your key and your plan

Limits

The search service

​Error codes

​Your request

​Your key and your plan

​Limits

​The search service

Error codes

Your request

Your key and your plan

Limits

The search service