Errors

Every error of the planned CoreLink API is an RFC 7807 problem document with a stable code, drawn from a single catalog.

Errors follow RFC 7807 and are sent as application/problem+json:

application/problem+json

{
  "type": "https://corelink.piensait.com/developers/errors/#insufficient_scope",
  "title": "The API key lacks the required scope",
  "status": 403,
  "detail": "This operation requires the scope `invoices:write`.",
  "instance": "/v1/invoices/inv_5KfT0a/issue#req_01J9Z6Q4N8",
  "code": "insufficient_scope"
}

code is stable: program against it.
title and detail are for people and may be reworded.
instance identifies this occurrence: quote it when you contact support.
errors lists the fields that failed, on validation_failed and invoice_validation_failed.

Catalog

The same catalog generates the responses in the API reference.

HTTP	Code	When	What to do
`400`	`validation_failed`	A query parameter is malformed or out of range: `limit` outside 1–100, an unknown `cursor`, a date that is not ISO 8601, or an unknown enum value in a filter.	Fix the request using `detail` and the `errors` array; retrying unchanged will fail again.
`400`	`idempotency_key_required`	A `POST` request arrived without an `Idempotency-Key` header.	Generate a unique key (a UUID v4 is fine) per logical operation and send it in `Idempotency-Key`. Reuse the same key when retrying that operation.
`401`	`unauthorized`	The `Authorization: Bearer` header is missing, or the key does not exist or was revoked.	Send a valid `clk_test_…` or `clk_live_…` key. Create or rotate keys in CoreLink › Settings › Developers.
`403`	`insufficient_scope`	The key is valid but was not granted the scope that the operation requires.	Ask a company administrator to create a key with the scope listed in the operation description.
`404`	`not_found`	No resource with that id exists in the company that owns the key. The API never reveals whether it exists in another company.	Check the id. Ids are only valid within the company (and environment) of the key.
`404`	`document_not_available`	The invoice exists but was never transmitted to the tax authority, so it has no PDF or XML representation yet.	Issue the invoice first (`POST /v1/invoices/{id}/issue`) and download once its status is `validated`.
`409`	`idempotency_conflict`	The `Idempotency-Key` was already used with a different request (another path or body). Replaying the same request with the same key returns the original response instead.	Use a new key for a new operation; only reuse a key to retry exactly the same request.
`422`	`invoice_not_issuable`	The invoice is not in status `issued` (ready to transmit): it is still a `draft`, already `transmitting` or `validated`, was `rejected` or ended in `error` (those require correction and a deliberate reissue in CoreLink), or was `voided` or `discarded`.	Read the invoice to see its `status`. Finalize drafts and correct rejected documents in CoreLink; the v1 API only transmits invoices that are ready.
`422`	`invoice_validation_failed`	Local checks before contacting the tax authority found missing or invalid data (for example a customer without identification document).	Fix the fields listed in `errors` in CoreLink and call issue again with a new `Idempotency-Key`.
`429`	`rate_limited`	The key exceeded its request quota for the current window.	Wait the number of seconds in the `Retry-After` header before retrying. Back off exponentially on repeated 429s.
`500`	`internal_error`	Something failed on CoreLink's side. It is logged with the `instance` identifier.	Retry later with the same `Idempotency-Key` if it was a `POST`. If it persists, contact support quoting `instance`.
`503`	`service_unavailable`	The electronic invoicing provider or the tax authority could not be reached.	Retry later honoring `Retry-After` when present. For `POST`, reuse the same `Idempotency-Key` so the operation is not duplicated.

Retries

Don’t retry 4xx errors unchanged: fix the request first. The exception is 429: wait for the seconds in Retry-After.
Retry 5xx errors with exponential backoff.
On a POST, retry with the same Idempotency-Key, so the operation is never repeated. Reusing a key for a different request returns 409 idempotency_conflict.