Errors

HTTP error shapes, 402 billing failures, and how to debug a failed NexDoc Design generation run.

code

{ "detail": "human-readable message" }

Sometimes detail is a structured object for validation errors.

Status codes

Code	Meaning	Action
`400`	Validation / unsupported upload type	Read `detail`. Usually a bad field or a file that is not png/jpg/gif/pdf.
`401`	Missing or invalid `NXD_API_KEY`	Create a key at app.nexdoc.design/keys.
`402`	Wallet empty or past due	`GET /v1/credits`, then add funds at app.nexdoc.design (minimum $10). No retry loops.
`404`	Unknown `job_id` / `run_id` / `file_id`, or it belongs to another organization	Check the IDs you persisted.
`409`	Cancel on a finished run	Fetch the run; do not retry cancel.
`503`	Queue / upstream unavailable	Retry once after 10 seconds.

Typical 402 bodies:

code

{ "detail": "insufficient credits" }

code

{ "detail": "account past due — add credits to continue" }

When status is failed, inspect:

code

curl -sS "$NXD_API_URL/v1/jobs/$JOB/runs/$RUN" \
  -H "Authorization: Bearer $NXD_API_KEY" | jq '{error, log_tail}'

Field	Use
`error`	Short failure reason
`log_tail`	Tail of agent output for debugging

Failed runs are not charged. Fix the inputs (instructions, content, format, assets) and retry once.