Errors

Errors use the standard response envelope with status: "error":

{
  "contract_version": "quoin-v4",
  "operation": "search",
  "request_id": "7d3f0c52-1b8e-4c0a-9a43-2f3c7b0f6a11",
  "status": "error",
  "data": null,
  "error": {
    "code": "invalid_request",
    "message": "filter: prefix and contains need 3+ characters and cannot include % _ or \\.",
    "retryable": false
  }
}

Branch on error.code, not on message. Codes are stable; messages may change.

Status	Code	Meaning	What to do
400	`invalid_request`	A parameter is missing, malformed or unknown, or a filter is invalid	Fix the request using the message
401	`invalid_key`	Missing or revoked API key	Check the `Authorization` header
402	`insufficient_balance`	Credit is used up and no payment method is saved	Add a payment method in the portal under Billing
403	`not_entitled`	The account is suspended or a payment needs attention	Check Billing in the portal
404	`not_found`	Nothing is published for this id, or the search matched nothing	Check the id; broaden the search
404	`unknown_resource`	No such endpoint	Check the path
410	`version_retired`	The path uses a retired API version	Use the version in `current_version`. See Versioning
405	`method_not_allowed`	Not a `GET` request	Use `GET`
409	`request_id_mismatch`	The `Idempotency-Key` was used for a different request	Use a new key
409	`request_replayed`	The key’s stored response has expired	Use a new key
422	`response_too_large`	The result exceeds 256 KiB	Lower `limit`
429	`rate_limited`	A rate limit was reached	Wait for `Retry-After` seconds. See Rate limits
503	`query_timeout`	The query took too long	Retry, or narrow a search
503	`service_unavailable`	Temporary problem	Retry with the same `Idempotency-Key` and backoff

retryable: true marks errors worth retrying unchanged. The first call after a few idle minutes can be slower than usual.

Get started

Core concepts

Guides

API basics

Resources