Errors

Envelope

Every error from the developer platform uses one consistent shape:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This operation requires the deploy:write scope.",
    "details": { }
  }
}

code is stable and machine-readable — branch on it, not on message. Every response also carries an x-request-id header; include it when reporting an issue.

Common codes

HTTP	Code	Meaning / action
400	invalid_request	Malformed body or parameters — the message names the field. Don’t retry unchanged.
401	authentication_failed	Missing/invalid/revoked key.
402	insufficient_balance	Wallet can’t cover the operation — top up or raise your spend cap.
403	insufficient_scope	Key lacks a scope (named in the message) — see Scopes.
403	dev_api_not_enabled	Account isn’t on Pro — the developer API is a Pro feature.
403	key_limit_reached	Too many active keys — revoke unused ones.
404	app_not_found	Unknown app id — or the key is pinned to other apps.
409	not_published / conflict codes	Operation invalid for current state (e.g. unpublishing a draft) — or an Idempotency-Key reused with a different body.
429	rate_limited / publish_velocity_exceeded	Throttled — honor Retry-After. See Rate limits.
5xx	internal_error	Something failed on our side — safe to retry with backoff; report persistent cases with the x-request-id.

Async failures

Asynchronous work (edits, deploys) can accept (202) and fail later — the failure arrives in the polled resource, not as an HTTP error:

{ "id": "…", "status": "failed", "error_code": "generation_failed", "error_message": "…" }

Check status on edits (completed / failed / cancelled) and deploys (deployed / failed), or subscribe to edit.failed webhooks. Failed generations are not billed.

Retry guidance

• Retry with backoff: 429 (after Retry-After) and 5xx.
• Fix first: 400, 401, 402, 403, 404, 409.
• Use Idempotency-Key on mutating requests you might retry, so a duplicate never double-executes.

MCP & A2A

MCP tools return the same envelope as a JSON string in the tool result. A2A uses JSON-RPC error codes (-32600, -32601, -32602, -32001) with the same underlying semantics — see A2A.