API errors

An error is always JSON, whatever the request asked for. This is the answer to a request with two mistakes (a missing client name and a date that does not exist):

{
  "error": {
    "code": "validation_failed",
    "message": "2 fields need attention.",
    "details": [
      {
        "field": "fields.client_name",
        "code": "required",
        "message": "client_name is required."
      },
      {
        "field": "fields.date",
        "code": "invalid_date",
        "message": "date must be a real date such as 2026-10-12."
      }
    ],
    "request_id": "req_…",
    "docs_url": "https://kouteisystems.com/docs/api/errors#validation_failed"
  },
  "credit_used": false
}

• code says what happened. Codes do not change; message texts may, so write your code against the codes.
• details, when present, lists each problem with its own code and, where it applies, the field it is about, as a path from the top of the body. It holds at most 50 entries.
• request_id identifies the request. It is also in the Koutei-Request-Id header. Quote it if you write to support@kouteisystems.com.
• credit_used is on every JSON answer to a document request. false means no credit was used. null means we could not confirm it either way: send the same request again with the same Idempotency-Key and you are charged once at most.
• New codes may be added. Treat a code you do not know by its HTTP status.

The API reference covers the routes, fields and limits these errors refer to.

The request itself is malformed: the body is not valid JSON, a top-level name is unknown or missing, or a header, query value or option has a value the API does not accept.

What to do: Read details: each entry names the part of the request and why it was refused. Fix it and send the request again.

credit_used: false.

The request uses a name that is held for a later version of the API. It wins over any field problem, so you get this error alone.

What to do: Remove the name. The API reference lists the reserved names.

credit_used: false.

The key is missing, malformed, unknown or revoked. The answer never says whether a key once existed.

What to do: Send "Authorization: Bearer" followed by a key that starts with kt_live_. Create one in Settings. A key that starts with sk_live_ never works; create a new one.

credit_used: false.

The account has no credit left for a final document. The body adds credits_remaining and period_end, the end of the current credit period.

What to do: Wait for the next credit period or change your plan. Previews and validation still work without credits.

credit_used: false.

The key is valid, but it is not allowed to do this. A Preview only key cannot make a final document.

What to do: Use a key with the scope the route needs, or create a Full access key in Settings.

credit_used: false.

There is no such path under /api/v1. Every path answers this while the API is switched off.

What to do: Check the path against the API reference.

credit_used: false.

There is no API template with that name. Templates that exist only in the web app are not offered here.

What to do: GET /api/v1/templates lists the templates you can use.

credit_used: false.

There is no such document in your history: the id is wrong, the document belongs to another account, or it is older than the history keeps.

What to do: Check the id. GET /api/v1/documents lists the documents you can read.

credit_used: not stated (this is not a document request).

Koutei does not store documents, so this route always answers this.

What to do: The file is only in the response to POST /api/v1/documents. To get it again, repeat that request with the same Idempotency-Key while the key is still remembered.

credit_used: not stated (this is not a document request).

The path exists, but not for this method. The Allow header lists the methods it takes.

What to do: Use one of the methods in the Allow header.

credit_used: false.

The request pins a template major version that is not the current one. The API never renders a different version in its place.

What to do: Check the template’s current version with GET /api/v1/templates, then update the pin and your fields.

credit_used: false.

A request with the same Idempotency-Key is still running.

What to do: Wait for the number of seconds in Retry-After and send the same request again. You get the finished document, or the request runs.

credit_used: false. The answer carries a Retry-After header, in seconds.

The Idempotency-Key was used for a document that can no longer be made byte for byte, because the template changed since. The API never returns different bytes under an old document id.

What to do: To make the document again, send the request with a new Idempotency-Key. That is a new document and uses a credit.

credit_used: false.

The request body is larger than the API accepts.

What to do: Send a smaller body. The API reference lists the size limit.

credit_used: false.

The PDF came out larger than the API can send back. Nothing was charged.

What to do: Make the document smaller, or ask for the file itself instead of JSON: the file form has the larger limit.

credit_used: false.

The body is not sent as JSON.

What to do: Send "Content-Type: application/json", in UTF-8.

credit_used: false.

One or more fields were refused. Every problem is listed at once, not only the first.

What to do: Read details: each entry gives the field, a code and a message. Fix them all and send the request again.

credit_used: false.

The Idempotency-Key was already used for a different request. A changed reference counts as a different request.

What to do: Send the original request again unchanged, or use a new key for the new request.

credit_used: false.

The template refused input that validation had accepted. That is a fault on our side, and it is logged.

What to do: Nothing was charged. Tell us the request_id so we can find it.

credit_used: false.

A limit was reached. details names which one.

What to do: Wait for the number of seconds in Retry-After, then try again. The RateLimit headers show how much of your limit is left.

credit_used: false. The answer carries a Retry-After header, in seconds.

The document was made, but we could not confirm whether the credit was taken, so credit_used is null.

What to do: Wait 35 seconds and send the same request with the same Idempotency-Key. If the credit was taken, you get the document without another one; if not, it is charged once.

credit_used: null (unknown: retry with the same Idempotency-Key).

Something failed on our side. credit_used is false unless the charge had already started, in which case it is null.

What to do: Try again with the same Idempotency-Key. If it keeps happening, tell us the request_id.

credit_used: false, or null (unknown: retry with the same Idempotency-Key).

The service that makes the PDF could not be reached. Nothing was charged.

What to do: Try again shortly with the same Idempotency-Key.

credit_used: false.

The service that makes the PDF is at capacity. Nothing was charged.

What to do: Wait for the number of seconds in Retry-After, then try again.

credit_used: false. The answer carries a Retry-After header, in seconds.

A shared limit was reached, or a part of the service that the request needs could not be reached. The request was not processed and nothing was charged.

What to do: Wait for the number of seconds in Retry-After, then try again.

credit_used: false. The answer carries a Retry-After header, in seconds.

The document took too long to make. Nothing was charged.

What to do: Try again. If the same document keeps timing out, make it smaller.

credit_used: false.