Skip to main content
Millwork API errors use JSON (application/problem+json) with type, title, status, and instance. Some also include detail or field-level errors. The error code is the last path segment of type; human messages may improve over time, so match the code. Read it before you retry. Some failures are safe to retry unchanged; others need a change first. When submitting a run with POST /v1/executions, send a request key in the Idempotency-Key header. Repeating that submission with the same key and body returns the original run instead of starting the work twice. Do not show raw provider errors to your users. This diagram shows when to repeat a run submission. If a run was accepted and then failed, read its status, events, and receipt before deciding what to do.

​
Safe retry rules

  • Retry a lost run submission with the same request key (Idempotency-Key) and identical body.
  • Reusing a request key with a different body returns idempotency_conflict.
  • For 429, wait for Retry-After or retry_after_s.
  • Do not retry invalid credentials or denied permissions unchanged.
  • For a live run that fails after acceptance, read its status, events, then receipt. Its platform fee was charged at acceptance. If Millwork failed it before any model attempt, the fee and the quota come back automatically. See Model access and billing.
Every write you make with an organization API key accepts a request key. For ordinary writes, retry with the same key, body, and caller to receive the recorded response instead of repeating the work. That holds for POST /v1/arms as well as for run submission. Run submission, template apply, and template resume require the key; every other organization write accepts one. Use the API reference for each endpoint’s request-key requirements. To get a new organization and its first key, follow Sign-in and access. API keys and webhook signing secrets are shown once. When you send a request key for key creation, webhook creation, or webhook secret rotation, repeating that successful request with the same key, body, and caller returns 409 idempotent_replay_secret_unavailable. It does not reveal or create a secret again. If you lost the response, list the keys or webhooks to find what was created. Revoke an unused API key before creating a replacement with a fresh request key. For an existing webhook, rotate its secret with a fresh request key and store the response securely. Failed requests keep their usual retry behavior.

​
Common errors

Provider connection reasons such as authentication, permission, and model_not_found have a separate recovery path. Read Provider connection help. Run reasons such as no_eligible_arms appear in events and receipts rather than as the API problem type. Read Run and result help.

​
When a connected provider fails

If a run was accepted, inspect its events and receipt before submitting again. The SDK sends requests to Millwork and returns its responses. Identify the failure before changing SDKs or repeating browser approval. A rejected provider credential needs an access check. An unavailable model or capacity problem needs the corresponding model or retry recovery. Only an explicit provider-credit error calls for checking that provider’s billing. Follow Provider connection help using the same connection and run IDs.

​
Fix invalid fields

For validation_failed, read each entry in errors: field names the part of the request to fix, and message explains why. Correct that field before retrying; repeating the same invalid request will not help. If the field is digest, your setup plan may have expired or stopped matching the organization. Refresh the plan and review it again. If it names a model, read the selection reason and check model availability. Share the field name and a redacted explanation when asking for help. Leave out the rejected value, credentials, consent links, and raw provider responses.

​
Ask for help

Include the instance value, endpoint, UTC time, type, and title in an email to support. Never include secrets, cookies, secure setup links, prompts, or customer data.