Skip to content

Latest commit

 

History

History
41 lines (27 loc) · 4.66 KB

migration.md

File metadata and controls

41 lines (27 loc) · 4.66 KB

Migrating to 2.47.0

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.

Two fields can be null

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 null value is not a finding and says nothing about whether the document was changed.

Two new status_reason values

An inconclusive result can carry status_reason analysis_incomplete or visible_signature_origin (see GET /result/{id}).

  • analysis_incomplete means 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_reason into a closed enum, add both values, and treat any value you do not recognise as inconclusive.

Timeouts return analysis_timeout

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

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.

Smaller changes

  • Test keys (htpbe_test_...) are strictly synthetic. GET /checks returns 200 with an empty data array and total: 0, and GET /result/{id} returns 404 not_found for 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_client when 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 filename of a check falls back to "document.pdf" when you send no original_filename and the last segment of the URL path is not a .pdf filename (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. Pass original_filename if you need a specific name (see GET /result/{id}).
  • URLs with embedded credentials (https://user:pass@…) are rejected with 400 invalid_url_format.
  • 5xx error bodies include a request_id. Quote it when you contact support.
  • 429 server_at_capacity is 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_pdf instead of 500. An analysis that is stopped by a fault on our side also returns 422 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.
  • details on invalid_pdf and download_failed errors is a fixed string. Do not parse it; branch on code.
  • pdf_version can be an empty string, and counters and flags can be 0 or false placeholders, on an inconclusive result with status_reason analysis_incomplete (see GET /result/{id}).
  • Some documents can return a different verdict, list of findings, confidence or status_reason than an earlier version returned. If a result issued earlier matters to you, re-submit the document.