Errors

Every error is an RFC 9457 problem document, Content-Type: application/problem+json, with a stable code:

{
  "type": "https://sealpost.app/errors/insufficient_scope",
  "title": "Forbidden",
  "status": 403,
  "detail": "This key lacks the api_keys:write scope.",
  "instance": "/v1/api-keys",
  "code": "insufficient_scope",
  "request_id": "0192c6d3-0f1e-7a21-9b1c-5e4d3c2b1a00"
}

Branch on code, never on detail: the wording can change, the codes do not.
request_id is also the Sign-Request-Id header. Quote it when you write to support@sealpost.app.
validation_failed and invalid_field_geometry add an errors list of {param, message}, one per problem.
Another account’s resource is always 404 not_found, never 403, so ids cannot be probed.

code	status	when	what to do
`invalid_request`	400	The body is not valid JSON, not an object, or the request could not be read.	Fix the request.
`invalid_header`	400	A header has an invalid value, e.g. `Idempotency-Key` empty or over 255 characters.	Fix the header.
`unauthenticated`	401	No `Authorization: Bearer sk_…`, a malformed key, or a key we do not know.	Check the key and the `Authorization: Bearer` header.
`api_key_revoked`	401	The key was revoked (`DELETE /v1/api-keys/{id}`).	Use another key. Revocation is permanent.
`api_key_expired`	401	The key passed its `expires_at`, including the 24 h overlap after a rotation.	Switch to the replacement key.
`insufficient_scope`	403	The key is valid but lacks the scope this operation needs.	Mint a key with the scope (a key can only grant scopes it has itself).
`live_key_required`	403	A test key tried to create, rotate or revoke a live key.	Use a live key for live-key management.
`not_found`	404	No such route, or no such resource in this tenant. Another tenant’s resource is also a 404, never a 403.	Check the id and the tenant the key belongs to.
`method_not_allowed`	405	The route exists but not for this HTTP method.	See the API reference.
`idempotency_in_flight`	409	A request with the same `Idempotency-Key` (same key, method and path) is still running. A request that died releases its lock after 60 s.	Wait and retry with the same key; you will get the stored response.
`upload_incomplete`	409	`POST /files/{id}/complete` was called before anything was PUT to the presigned URL.	Upload the bytes to `upload_url` with the returned headers, then call `complete` again.
`file_too_large`	413	A file is over 25 MB (10 MB inline as base64).	Inline base64 over 10 MB: upload it as multipart, from a URL or through `POST /files/presign` (all up to 25 MB). Over 25 MB: split or compress the document.
`validation_failed`	422	A value is invalid. `errors[]` names each `param`.	Fix the named fields.
`invalid_file`	422	The bytes are not a PDF the document service can open, or the file is empty. Only PDF is accepted in this release.	Send a valid PDF; convert other formats before upload.
`invalid_field_geometry`	422	A field’s box leaves its page, or names a page the file does not have. `detail` names the field identifier and the page size in points; `errors[]` names the field.	Fix the coordinates or the `unit` (see Files and envelopes).
`idempotency_key_reused`	422	The same `Idempotency-Key` was sent with a different request body within 24 h.	Use a new key for a new request.
`rate_limited`	429	The key is over its per-minute budget (600 live, 60 test). `Retry-After` says how long to wait.	Back off for `Retry-After` seconds.
`pdf_service_unavailable`	503	A file could not be inspected just then. Nothing was stored. `Retry-After` is set.	Retry the request after `Retry-After` seconds, with the same `Idempotency-Key`.
`internal_error`	500	Something failed on our side.	Retry with the same `Idempotency-Key` (a 5xx is never stored); contact support with the request id if it persists.

The list is closed. A new code arrives only with a new feature, and is added here when that feature ships.