Error Codes

Errors you can handle.
Predictably.

on8.ai uses standard HTTP status codes and one JSON envelope for every response. Each error code tells you whether retrying is safe.

Error body

Every response carries success. Successful calls put the payload in data; failures put a machine-readable code and a human-readable message in error. Request-shape validation failures (422) add a details array; service-level rule failures (400) carry code and message only.

422 Unprocessable Entityapplication/json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "'query' must not be empty.",
    "details": [ { "field": "query", "message": "'query' must not be empty." } ]
  }
}

Standard codes

401UNAUTHORIZEDNo usable credentials: the `Authorization` header is missing, empty, or uses a scheme other than `ApiKey` without carrying an on8 key (for example a `Bearer` token that is not an on8 key).No, send `Authorization: ApiKey <your key>`.

401API_KEY_WRONG_SCHEMEAn on8 key arrived with the wrong scheme: as `Bearer`, or in the `X-API-Key` header. The message says which and names the format: "An API key was sent with the Bearer scheme. Send it as 'Authorization: ApiKey <key>'."No, send the same key as `Authorization: ApiKey <your key>`.

401INVALID_API_KEYAn `ApiKey` was sent but not recognised: it is wrong, revoked or expired.No, check the key or issue a new one in the portal.

403SCOPE_NOT_GRANTEDThe endpoint is not available to API keys (portal session only): "This endpoint is not available to API keys. Use a signed-in session, or call an endpoint that is available to API keys."No, use a signed-in session or a documented API endpoint.

403API_PERMISSION_DENIEDThe key's level on the endpoint's module is below the one required: "API key lacks Delete on module 'portal.ongoing-monitoring'." The message names the level and module; each endpoint in the API Reference lists both. The level that counts is the lower of the key's own and the current platform maximum for the module, so a lowered maximum also refuses an existing key.No, create a new key with that module at that level (permissions cannot be edited after creation).

400NO_PERMISSIONSKey creation granted no module a level above None: "Grant at least one module a level above None."No, pick at least one module.

400UNKNOWN_MODULEKey creation named a module that is not an API module: "Unknown or non-API module(s): <modules>."No, use the modules offered in the portal.

400PERMISSION_ABOVE_MAXIMUMKey creation asked for more than the platform maximum: "Requested level exceeds the platform maximum for: <module> (<requested> > <maximum>)."No, lower the level to the maximum shown in the portal.

403IP_NOT_ALLOWEDThe caller's IP is outside the key's allowlist (or inside its blocklist).No, update the list in the portal.

403PACKAGE_REQUIREDThe tenant has no active package or live demo: "An active package or demo is required for this module." Checked before every screening, batch and monitoring endpoint runs.No, activate a plan.

403NO_SUBSCRIPTION"Tenant has no active subscription." The metered call found no active or trialing subscription to count against.No, activate a plan.

403FEATURE_NOT_INCLUDED"Plan does not include '<feature>'.", e.g. `screenings_monthly` or `prekyc_monthly`. On an orchestrated screen one unlicensed module refuses the whole call.No, list only the modules your plan has, or upgrade.

403PLAN_REQUIREDThe endpoint needs a higher plan (for example entity neighbours on Enterprise).No, upgrade.

402QUOTA_EXCEEDEDThe monthly allowance for a feature is used up and overage is blocked: "Monthly quota for '<feature>' exhausted." (e.g. `screenings_monthly`), or on a demo "Demo query quota exhausted."No, wait for renewal or raise the plan.

400EMPTY_QUERYNo subject was supplied (name, BIC legs, IMO/MMSI/name, ISIN ...).No, fix the request.

400EMPTY_BATCHThe batch had no named subjects (or, on the synchronous batch, no subjects at all).No, fix the request.

400BATCH_TOO_LARGEA synchronous batch holds at most 100 subjects; a batch job at most 10,000.No, split, or use batch jobs.

400EMPTY_FILEA batch upload had no file in the multipart field named `file`, or the file was empty.No, send the file as multipart/form-data.

400UNSUPPORTED_FORMATA batch upload whose extension is not .csv, .xlsx, .xls or .json.No, convert the file.

422FILE_EXTENSION_MISMATCHA batch upload whose contents do not match its extension (a workbook named .csv, say). The extension picks the parser, so it has to be right.No, rename the file to its real type.

400PARSE_ERRORA batch upload that could not be read into rows, e.g. a CSV whose columns no separator could split.No, fix the file.

400INVALID_INPUTAn orchestrated screen whose entity has neither a name nor an identifier value.No, fix the request.

422 / 400VALIDATION_ERRORA field is missing or malformed. Request-shape failures answer 422 with an `error.details` array; service-level rule failures answer 400 with code and message only. On the screening endpoints a name or query longer than 512 characters is refused with 400 "The search query is limited to 512 characters." before anything is billed.No, fix the request.

422USE_DEDICATED_MODULEThe general search received a non-name input: an e-mail address, a phone number, a crypto wallet, an IMO or MMSI vessel number, an ISIN, a VAT/TIN number or a registration or tax number. Not metered.No, call the dedicated endpoint named in the message.

409DUPLICATE_SUBJECTThe subject is already under active monitoring; the message names the existing subject's id.No, use that id instead of enrolling again.

409INVALID_STATEA batch job re-queue on a job that is not `Failed` or `PartialFailure`.No, only a failed job can be re-queued.

415UNSUPPORTED_MEDIA_TYPEThe body was sent without `Content-Type: application/json`.No, add the header and send the body as JSON.

405METHOD_NOT_ALLOWEDThe path exists but does not accept this HTTP method. Most screening endpoints are POST, but not all: entity profile, neighbours, officers, institution lookup, place search and the reference lists are GET, as are the batch job and monitoring reads.No, use the method shown in the API Reference.

404NOT_FOUNDNo endpoint matches that method and path (usually a typo or a missing `/api/v1` prefix) - or the id in the path does not resolve: a batch job answers "Job not found.", a monitored subject "Resource not found". A deleted record, another tenant's, and one your caller cannot see all answer the same.No, check the path or the id.

429RATE_LIMIT_EXCEEDEDA fixed-window limit was hit: the /screening endpoints allow 120 requests per minute per tenant - one window shared by all of the tenant's API keys and portal users - and batch upload 60 per minute per user, or per tenant for API keys.Yes. Honour the Retry-After header; fall back to exponential backoff with jitter.

502SMARTSANCTION_UNAVAILABLEThe screening engine did not answer.Yes, backoff and retry; persistent failures are an incident.

503ADVERSE_MEDIA_DEEP_UNAVAILABLEThe deep adverse-media tier is not enabled for this deployment.No, call without `deep`.

500INTERNAL_SERVER_ERRORUnhandled failure; the body carries a `correlationId` to quote to support.Once, then contact support with the correlationId.

Retry only the retryable

Retry 429 and 502 with exponential backoff. Never retry 400, 401, 402, 403 or 422; they need a code, key or plan fix.

Branch on code, not message

The code is stable; messages may change. Always switch on the code.

See errors per endpoint

Each endpoint documents its specific error responses in the API reference.

Open API Reference