Errors & rate limits

Error shape

Errors return a non-2xx status and a JSON body with a message:

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

Status	Meaning	Typical cause
`400`	Bad request	Missing/invalid field (e.g. no `tax_software`, non-numeric `tax_year`), no documents uploaded
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Key lacks the required scope
`404`	Not found	Unknown client/submission id (or not in your org)
`409`	Conflict	Client already has an active submission; or documents still uploading (call finalize first)
`429`	Too Many Requests	Rate limit exceeded — see below

Write endpoints are rate limited per API key. When exceeded you get 429 with a Retry-After header (seconds) and:

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

Back off and retry after Retry-After.

Don't double-submit: a client allows only one active submission (409). Track the sub_… id you got back rather than re-creating.
Network errors on create are safe to retry; if you're unsure whether a client/submission was created, GET /v1/clients or GET /v1/submissions to check before retrying.
Download URLs (download_url) are presigned and expire — re-fetch them from the submission instead of caching long-term.