Changes to the API's responses and error codes in version 2.47.0, compared with 2.44.7, the previous version in service. No endpoint, field, verdict or marker id was removed or renamed. The changes below can still break a strictly typed client, so check your integration against each of them.
xref_count (GET /result/{id}) and has_incremental_updates (GET /result/{id} and GET /checks) can now be null. null means the value could not be established for that document, or was not recorded for an older check. Earlier versions returned 0 or false in those cases, so results of older checks can show null too.
- Model both fields as nullable. The OpenAPI document declares them as
["integer", "null"]and["boolean", "null"]. - A
nullvalue is not a finding and says nothing about whether the document was changed.
An inconclusive result can carry status_reason analysis_incomplete or visible_signature_origin (see GET /result/{id}).
analysis_incompletemeans the check could not be completed in full. Such a result is never a clean result, and it uses a credit or quota like any other delivered result.- If you deserialise
status_reasoninto a closed enum, add both values, and treat any value you do not recognise asinconclusive.
An analysis that does not finish within its time limit returns 422 with code analysis_timeout instead of invalid_pdf (see Analysis Timeout). The body keeps its shape (error, code, details). No result is stored and no credit or quota is used.
- Unlike
invalid_pdf, a timeout can succeed on retry: wait about a minute and retry with backoff. - Treat any error code you do not recognise as a failed request.
creator and producer can be shortened copies of a longer value. The required boolean fields creator_truncated and producer_truncated are true when that happens. The tool, creator and producer filters of GET /checks match the stored, possibly shortened value.
- Test keys (
htpbe_test_...) are strictly synthetic.GET /checksreturns200with an emptydataarray andtotal: 0, andGET /result/{id}returns404 not_foundfor any well-formed id outside the predefined synthetic ids, including a real check id created by the same account with a live key. Earlier versions could return those real checks to a test key. Read real results with a live key. - A request is refused with
403 inactive_clientwhen a live key has been deactivated or the account behind the key has been disabled. A test key now also receives it when its account has been disabled. Do not retry; contact support. - The
filenameof a check falls back to"document.pdf"when you send nooriginal_filenameand the last segment of the URL path is not a.pdffilename (for example a share-link token, an ID, or an empty path). Earlier versions stored that last segment as it was; checks created before this version keep their stored name. Passoriginal_filenameif you need a specific name (seeGET /result/{id}). - URLs with embedded credentials (
https://user:pass@…) are rejected with400 invalid_url_format. 5xxerror bodies include arequest_id. Quote it when you contact support.429 server_at_capacityis also returned when your account already holds its share of the analysis queue, counted across all of its API keys, so your account can receive it while other accounts are served (see 429 Too Many Requests). Retry handling is unchanged.- A file whose internal structure cannot be read returns
422 invalid_pdfinstead of500. An analysis that is stopped by a fault on our side also returns422 invalid_pdf. In both cases no result is stored and no credit or quota is used (see Unreadable Document Structure and Analysis Interrupted). Do not retry either unchanged. detailsoninvalid_pdfanddownload_failederrors is a fixed string. Do not parse it; branch oncode.pdf_versioncan be an empty string, and counters and flags can be0orfalseplaceholders, on aninconclusiveresult withstatus_reasonanalysis_incomplete(seeGET /result/{id}).- Some documents can return a different verdict, list of findings, confidence or
status_reasonthan an earlier version returned. If a result issued earlier matters to you, re-submit the document.