Errors

Whichever endpoint fails, the error body has the same shape, so you can handle errors in one place. Branch on error.code, which is stable. Show error.message to a developer if you like, but don’t parse it, because the wording may change.

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": [
      {
        "origin": "string",
        "code": "too_small",
        "minimum": 1,
        "inclusive": true,
        "path": ["document"],
        "message": "Too small: expected string to have >=1 characters"
      }
    ]
  }
}

Member	Type	Always present	Description
error.code	string	yes	Machine-readable code from the table below. Stable: branch on this.
error.message	string	yes	Human-readable explanation. May change; don’t parse it.
error.details	array	no	Present on 400 invalid_request, with one entry per problem. Each has a code (such as too_small or invalid_value), a path to the bad part of the body, a message, and the constraint it broke (minimum, values, pattern and so on).

Error codes

Status	code	Cause	What to do
400	invalid_request	The body or the schema is invalid, or an edit sent an altered session or a stale plan.	Fix the request using details. Retrying it unchanged will fail again.
401	unauthorized	Missing, unknown, revoked or expired key, or a key without the required scope.	See Authentication.
404	not_found	No such endpoint.	Check the method and URL.
429	rate_limited	The key’s rate limit is reached.	Wait and retry with backoff.
500	internal_error	An unexpected failure on our side.	Retry later; contact support if it persists.
502	upstream_error	The extraction service failed.	Retry later; contact support if it persists.
503	pipeline_unavailable	The extraction service is unavailable.	Retry shortly with backoff.
501	not_implemented	Reserved for endpoints that exist but aren’t available yet. No endpoint returns it today.	Nothing to do.

Examples

A typo in the path (extraction instead of extractions) gets 404:

POST /v1/extraction

{ "error": { "code": "not_found", "message": "No such endpoint." } }

Editing with a session that was changed, or with a different document than the one it was made for, gets 400:

{
  "error": {
    "code": "invalid_request",
    "message": "The session doesn't match this document and schema, or was altered."
  }
}

Not every empty field is an error

An extraction can succeed while some of its fields have no value, because the document doesn’t mention them or because the evidence for them conflicts. Tickmarks reports that per field, not as an HTTP error, so a 200 doesn’t mean every field was filled. Check fields[name].status in the response to find out why a field is empty.