Errors

Every error the API returns, as RFC 9457 problem details.

Every failure is an RFC 9457 problem document (application/problem+json) whose type URI ends in one of the slugs below, with a machine-readable error property carrying the same code. This page is a build gate: the server cannot ship an error code that is not documented here.

{
  "type": "https://api.accountflow.com/errors/resource-not-found",
  "title": "Resource Not Found",
  "status": 404,
  "detail": "Resource not found",
  "error": "resource_not_found"
}

Code	Status	Meaning	What to do
`resource_not_found`	404	The id doesn't exist within your reach. Deliberately indistinguishable from "exists but isn't yours" and "deleted".	Check the id; check you're using the right client for the right organization.
`duplicate_resource`	409	The thing you're creating already exists (same company number in the org, same policy name, same assignment, duplicate rule).	Fetch the existing resource instead, or change the distinguishing field.
`conflict`	409	Valid request, wrong state: an in-flight job for the same scope (`jobId` extension names it), an expired/incomplete upload slot, an archived policy, a GL line already reconciled this year, a missing GL mapping.	Read the `detail` and extensions; resolve the state (poll the job, finish the upload, unmatch first) and retry.
`deleted_by_organization_cascade`	409	The company was deleted as part of its organization's deletion — restoring it alone is impossible.	Restore the organization instead.
`validation_failed`	400	The request is malformed: a required field is missing or blank, a value is out of range.	Fix the request body; the `detail` names the field.
`unprocessable`	422	The request is well-formed but semantically wrong: unknown role, foreign company on a rule, size over the type's cap, declared-vs-actual mismatch, an invalid organization number.	The `detail` explains the rule that failed.
`unauthorized`	401	Missing, expired, or invalid token. `WWW-Authenticate` says which.	Fetch a fresh token; check audience and issuer.
`forbidden`	403	Authenticated, but this action is denied.	Check the client's provisioning.
`capability_denied`	403	This kind of principal can never do this (e.g. a per-user client managing access policies; an interactive session writing).	Use a system client for admin surfaces.
`insufficient_scope`	403	The token lacks a required scope — `WWW-Authenticate` names it (`scope="..."`).	Request the scope (interactive) or have it granted (machine clients).
`rate_limited`	429	Plan quota exceeded. `Retry-After` says when to come back.	Back off per `Retry-After`; consider the premium plan for sustained volume.
`idempotency_key_missing`	400	Every mutation requires an `Idempotency-Key` header.	Send a unique key per logical operation; retries reuse the same key.
`idempotency_key_reused`	422	The key was used before with a different request body.	Never reuse keys across different operations; generate a UUID per logical action.
`idempotency_in_flight`	409	The same key's first request is still executing. `Retry-After` is set.	Wait and retry with the same key — you'll get the stored response.
`invalid_cursor`	400	The cursor is expired, tampered with, from another client, or from a request with different filters.	Restart from the first page. Never modify or share cursors.
`method_not_allowed`	405	The path exists; the verb doesn't.	Check the reference.
`internal_error`	500	Our bug. The response's `requestId` lets support find it immediately.	Retry with the same Idempotency-Key (safe); report the `requestId` if it persists.
`not_implemented`	501	Documented but not yet available in this environment.	Check the changelog.
`service_unavailable`	503	A dependency (e.g. the authorization backend) is unavailable. Fails closed — never wrong data.	Retry with backoff; mutations are idempotent-safe to retry with the same key.
`unsupported_media_type`	415	The declared content type isn't accepted (document uploads validate against the allowlist).	`GET` the reference for accepted types and size caps.