Errors & rate limits

Error shape

Errors return a non-2xx status and a JSON body with a stable, machine-readable code and a human-readable message:

{ "code": "insufficient_scope", "message": "API key is missing required scope 'submissions.write'" }

Branch on code, not message. The message wording may change; the code is stable (we add new codes rather than renaming existing ones). Every error carries a code — a generic one derived from the status, plus specific codes that disambiguate cases sharing a status.

Error codes

The codes that disambiguate same-status conditions (handle these differently):

This table isn't exhaustive — other validation failures also carry a specific code (e.g. invalid_cursor, invalid_limit, invalid_content_md5 on a bad request). Generic per-status codes (bad_request 400, unauthorized 401, forbidden 403, not_found 404, conflict 409, payload_too_large 413, unprocessable_entity 422, internal_error 500) are used where no more specific code applies. In all cases, branch on code and treat an unrecognized one by its HTTP status.

Rate limits

Both write endpoints and the submission status reads (GET /v1/submissions/{id} and GET /v1/submissions) are rate limited per API key. We don't publish specific limits (they may change), so design for the 429 rather than a fixed number. When you exceed the limit you get a 429 with a Retry-After header (seconds) and a matching body field:

{ "code": "rate_limited", "message": "Rate limit exceeded", "retry_after_seconds": 42 }

Back off and retry after the delay — read it from either the Retry-After header or retry_after_seconds.

Webhooks are the recommended way to track a submission's status; polling GET /v1/submissions/{id} is a supported fallback. Configure a submission_updated_webhook_url on your API key and we'll push a signed submission.updated event on every status change (see Webhooks) — no polling loop to rate-limit. If you do poll, poll a few times a day (not in a tight loop), and honor Retry-After on a 429.

Idempotency & retries

• Don't double-submit: a client allows only one active submission (409). Track the submission id you got back rather than re-creating.
• Network errors on create are not automatically safe to retry — a timed-out POST may still have succeeded server-side. If a create times out, GET /v1/clients or GET /v1/submissions to confirm whether the resource was created before sending another create request.
• Download URLs (download_url) are presigned and expire — re-fetch them from the submission instead of caching long-term.

Cancellation codes

When a submission's status is cancelled, the submission carries a human-readable cancellation_reason and a stable, machine-readable cancellation_code you can branch on. The codes are stable — we add new ones rather than renaming existing ones.

Some cancellations are the taxpayer's/firm's to resolve (e.g. encrypted_file, mismatched_client); as an integrator you'll typically forward those back to the firm. Because you talk to us on the firm's behalf, decide per code whether to surface it to the firm or handle it yourself.