Errors

Every error of the API is an RFC 9457 problem, with Content-Type: application/problem+json:

{
  "type": "https://docs.accountcloud.io/errors/invalid_api_key",
  "title": "Invalid API key",
  "status": 401,
  "detail": "The API key is not valid. Check that you copied it completely, or create a new one in the portal.",
  "code": "invalid_api_key",
  "request_id": "req_01jbxk3v6c9m2q8r4t5w7y0z1a"
}

Field	What it is
`type`	A link to the explanation of this error, below. Ends in the `code`.
`title`	A short summary of the error type.
`status`	The HTTP status code, the same as the status of the response.
`detail`	What went wrong this time, for a human. The text can change; do not parse it.
`code`	The stable, machine-readable code. Branch on this one. A code never changes meaning; new errors get new codes.
`request_id`	The id of the request, also in the `X-Request-Id` header. Quote it when you contact support.

Some errors add fields of their own, listed with the code. A validation_failed has the messages per field in errors:

{
  "type": "https://docs.accountcloud.io/errors/validation_failed",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request body or parameters are not valid.",
  "code": "validation_failed",
  "request_id": "req_01jbxk3v6c9m2q8r4t5w7y0z1a",
  "errors": {
    "address.country": ["The selected address.country is invalid."]
  }
}

An error is not charged: its AccountCloud-Charged header is 0.0000. There is one exception: a company_not_found for a Dutch company costs what the KvK charges us for the lookup, at cost price.

What to do with an error

4xx: fix the request or the key; sending it again unchanged gives the same answer.
429 and 503: wait the number of seconds in Retry-After, then try again.
500: try again later, with a growing pause. For a POST, send an Idempotency-Key, so a retry never does the work twice.

Error codes

Authentication and access

Code	Status	Meaning
`unauthenticated`	401	No API key. Send `Authorization: Bearer ac_live_…` or `ac_test_…`.
`invalid_api_key`	401	The key does not exist or was revoked. After 20 of these per minute from one IP address, that address gets `rate_limit_exceeded` instead.
`api_key_expired`	401	The key passed its end date, or it was rotated and its overlap is over. Use its replacement.
`account_inactive`	403	The account is suspended or closed. Contact support.
`account_disabled`	403	We switched off API access for this account for now. Contact support.
`ip_not_allowed`	403	The key has an IP allowlist, and your address is not on it.
`insufficient_scope`	403	The key may not call this operation. With `required_scope` and `granted_scopes`.
`subscription_ended`	403	A live key of an account whose base subscription was stopped. Test keys keep working; a paid top-up starts a new subscription.
`forbidden`	403	The key may not do this.

The request

Code	Status	Meaning
`bad_request`	400	The request could not be understood.
`invalid_idempotency_key`	400	The `Idempotency-Key` header must be 1 to 255 visible ASCII characters. See idempotency.
`invalid_entity_reference`	400	The `AccountCloud-Entity` header must be 1 to 255 visible characters.
`request_failed`	4xx	Another client error; `status` has the code.
`not_found`	404	The path or the resource does not exist.
`country_not_supported`	404	The operation does not support this country. With `supported_countries`.
`method_not_allowed`	405	This HTTP method does not exist on this path; the `Allow` header lists the ones that do.
`conflict`	409	The request conflicts with the current state of the resource.
`idempotency_key_reused`	409	This `Idempotency-Key` was used before for a different request. See idempotency.
`idempotency_key_in_use`	409	A request with this `Idempotency-Key` is still running. Try again after `Retry-After` (1 second). See idempotency.
`validation_failed`	422	The body or the parameters are not valid. The messages per field are in `errors`.

Limits and credit

Code	Status	Meaning
`insufficient_credits`	402	Your credit does not cover this call. With `price`, `available` and `currency`. Top up in the portal, or switch on automatic top-up.
`rate_limit_exceeded`	429	Too many requests for this key this minute. Wait for `Retry-After`. See rate limits.
`daily_quota_exceeded`	429	The daily quota of the account is used up. It resets at 00:00 UTC.
`monthly_cap_reached`	429	This key reached its monthly spending cap. Raise the cap in the portal, or wait for the next calendar month (UTC); `Retry-After` says how long.

Availability

Code	Status	Meaning
`server_error`	500	Something went wrong on our side. Try again later; quote the `request_id` if it persists.
`test_mode_not_supported`	501	This operation has no test mode yet. With `operation`. See test mode.
`api_unavailable`	503	The API is switched off for now. Try again after `Retry-After`.
`product_unavailable`	503	This product is switched off for now. Try again after `Retry-After`.
`operation_unavailable`	503	This operation is switched off for now, or it has no price yet, for every country or for the one you asked. Try again after `Retry-After`.
`provider_unavailable`	503	The source behind this operation is down, such as a trade register or VIES. Nothing was charged. With `provider_status`. Try again after `Retry-After`.
`service_unavailable`	503	The service is unavailable for now, for example storing a document or validating a UBL file. Nothing was charged. Try again later.

Documents (OCR and UBL)

See documents.

Code	Status	Meaning
`file_missing`	422	No file. Send `file` as a JSON object with `name` and `content_base64`, or as a multipart file field.
`invalid_base64`	422	`file.content_base64` is not valid base64. A prefix such as `data:application/pdf;base64,` is allowed.
`file_too_large`	413	The file is larger than 10 MB after decoding. With `max_bytes`.
`unsupported_media_type`	415	The file is not a PDF, JPEG or PNG. The type is decided from the content, not from the file name or a declared type.
`encrypted_pdf`	422	The PDF asks for a password, or cannot be opened.
`too_many_pages`	422	The PDF has more pages than a document may have. With `max_pages` (now 50) and `pages`.
`invalid_option`	422	An option has a value that is not allowed, such as `processing: "fast"`. With the option in `field`, and the messages per field in `errors`, as with `validation_failed`.
`verified_not_enabled`	403	`processing: verified` is switched off for this account. Contact support.
`verified_daily_limit`	429	The account sent five times its daily maximum of verified documents on one working day. With `daily_max`. Try again on the next working day, or contact support.
`document_not_found`	404	The document does not exist, belongs to another account or environment, or was deleted.
`document_not_ready`	409	The document is not `completed` yet, so it has no UBL. Wait for `document.completed`. Also when no UBL could be made from the result: see `ubl.errors` on the document.
`document_rejected`	409	The document was rejected, so it has no UBL. See `rejection` on the document.
`content_purged`	410	The content of the document was deleted at the end of its retention period, so there is no UBL any more. The metadata is still there.
`feedback_window_closed`	409	The original of the document is deleted. Send the file again with the report, as `file.content_base64`.
`file_hash_mismatch`	422	The file you sent with the report is not the original of the document: its SHA-256 differs.
`unknown_field`	422	A `field` in the report is not a field of the result. With `field`.
`feedback_limit_reached`	429	The account sent the maximum number of reports for today, 100 unless agreed otherwise. It resets at 00:00 UTC; `Retry-After` says how long.

Company data and VAT numbers

See company data and VAT numbers.

Code	Status	Meaning
`company_not_found`	404	The register has no company with this number. With `country` and `number`. For NL this costs what the KvK charges us for the lookup, at cost price; any other “not found” is free.
`company_not_cached`	404	You asked `freshness=cached`, and we hold no copy of this company yet. Ask with `freshness=auto` or `freshness=live` to fetch it from the register. With `country` and `number`. Free.
`register_restricted`	403	The data of this register is not available to your account, also not with a test key. Dutch company data comes from the KvK, whose terms do not allow us to pass it on. With `country`. Contact support.