Errors

Every error has the same envelope. Branch on type for broad handling and on code for exact handling; codes are never renamed. Each doc_url in an error opens the page for its code below. 80 codes.

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_failed",
    "message": "`limit` must be between 1 and 100.",
    "param": "limit",
    "request_id": "req_01j9zr3m5k8q2w7x4t6v0b1c9d",
    "doc_url": "https://docs.deedglass.com/errors/validation_failed"
  }
}

Invalid request (`invalid_request_error`)

Code	HTTP	Default message
`approval_expired`	409	This approval expired before anyone decided. Nothing ran. Ask the agent to try again if it’s still needed.
`tool_unknown`	404	No connector provides this tool. Check the name, or add a connector in Console › Connectors.
`idempotency_conflict`	422	This Idempotency-Key was already used with a different request. Use a new key for a new request.
`validation_failed`	400	A field in the request isn’t valid. The param field names it.
`not_found`	404	There’s no object with that id in this org. Check the id.
`conflict`	409	That conflicts with the current state. Fetch the latest version, then retry.
`method_not_allowed`	405	This method isn’t supported on this path. The Allow header lists the ones that are.
`request_too_large`	413	The request body is too large for this endpoint. Send a smaller body.
`unsupported_media_type`	415	Send the body as JSON, with Content-Type: application/json.
`invalid_json`	400	The body isn’t valid JSON. Fix it and retry.
`api_version_invalid`	400	Deedglass-Version isn’t a known version. Use 2026-10-01, or leave it out to use your org’s pinned version.
`idempotency_key_invalid`	400	Idempotency-Key must be 1 to 255 printable ASCII characters.
`idempotency_key_in_use`	409	A request with this Idempotency-Key is still running. Retry in a moment.
`login_link_invalid`	400	This sign-in link has expired or was already used. Get a new one at /login.
`login_code_invalid`	400	That code doesn’t match, or it has expired. Check the latest email, or get a new code.
`last_owner`	409	This org needs at least one owner. Make someone else an owner first.
`policy_invalid`	400	The policy wasn’t accepted. The diagnostics list each problem with its line and a hint.
`credentials_missing`	409	This connector has no credentials yet. Store them with deedglass connector credentials set, then retry.
`destination_blocked`	400	The connector’s destination is blocked by Deedglass’s network rules. An admin can see why in Console › Connectors.
`statement_refused`	400	Refused by the Postgres connector. Deedglass runs one plain statement per action, and never transaction control, schema changes or schema deedglass.
`row_limit_exceeded`	400	The statement changed more rows than this connector allows. Nothing was committed. Narrow the WHERE clause.
`witness_not_configured`	409	Checks aren’t on for this connector, so it has no decoder. Turn on witness.enabled in its config first.
`approval_decided`	409	This approval was already decided. Console › Approvals shows who decided and when.
`already_countersigned`	409	You already countersigned this. It needs another person.
`context_changed`	409	What you reviewed is out of date. Reload the approval and review it again.
`stripe_live_key_refused`	400	This is a live-mode Stripe key. Deedglass connects to Stripe sandboxes only. Use a restricted key that starts with rk_test_.
`action_executing`	409	It’s running now and can’t be cancelled. Its deed will show what happened.
`from_denied`	400	From on deedglass.com is never allowed for outbound mail. Use the sending-domain mailbox.
`undo_unavailable`	409	Undo isn’t available for this action. The checks field lists each failing check with its fix.
`undo_plan_stale`	409	The rows changed since you previewed this undo. Preview it again and use the new plan.
`already_undone`	409	This action was already undone, or an undo of it is waiting. Look at the action’s undo object.
`undo_conflict`	409	A row changed after the undo’s plan was made, so Postgres rolled the undo back. Nothing was changed. Preview the undo again.
`replay_too_large`	400	This replay covers more than 1,000,000 actions. Narrow the window with from and to.
`replay_window_invalid`	400	The window must start before it ends, and it can be at most 90 days long. Send from before to.
`suggestion_stale`	409	The policy changed since this suggestion was written. Generate suggestions again: POST /v1/suggestions/generate.
`shadow_slot_taken`	409	Another version is already running in shadow. Promote or clear it first, or accept with replace_shadow: true to replace it.
`suggestion_decided`	409	This suggestion was already decided. Look at its status, or generate suggestions again.
`observe_not_enabled`	409	Observe mode is off for this connector. Turn it on in Console › Connectors, or set witness.observe.enabled: true in its config.

Authentication (`authentication_error`)

Code	HTTP	Default message
`invalid_api_key`	401	The API key isn’t valid. Check that you copied all of it (it starts with dg_live_ or dg_test_), or create a new one in Console › Agents.
`api_key_revoked`	401	The API key has been revoked. Create a new key in Console › Agents.
`api_key_expired`	401	The API key expired after it was rolled. Use the new key, or create one in Console › Agents.
`authentication_required`	401	This endpoint needs an API key (Authorization: Bearer dg_live_…) or a Console session.
`session_expired`	401	Your session ended. Sign in again.
`approval_link_invalid`	401	This approval link has expired or was already used. Open Console › Approvals.

Permission (`permission_error`)

Code	HTTP	Default message
`agent_suspended`	403	This agent is suspended. An admin can resume it in Console › Agents.
`agent_stopped`	403	This agent is stopped. Deedglass refuses its calls until an admin starts it in Console › Agents.
`org_stopped`	403	All agents in this org are stopped. An owner can start them again in Console › Settings.
`insufficient_scope`	403	This key doesn’t have the scope this endpoint needs. Create a key with that scope in Console › Agents.
`intent_required`	403	This agent must sign its requests. Send a Deedglass-Intent header.
`intent_invalid`	403	The signed intent doesn’t match this request. Sign the exact tool and arguments you send.
`intent_replay`	403	This signed intent was already used. Sign a new one with a fresh nonce.
`csrf_failed`	403	This request is missing its security token. Reload the page and try again.
`insufficient_role`	403	Your role in this org doesn’t allow this. Ask an owner to change your role.
`approver_not_eligible`	403	You’re not an approver for this rule. Ask one of its approvers to countersign.
`self_approval`	403	This action runs on your behalf, so another approver has to countersign it. You can still deny it.
`approval_needs_person`	403	Approvals need a person. Agents and API keys can’t countersign. Use Console › Approvals or the emailed link.
`approval_link_review_only`	403	Your org decides approvals in the Console. Open Console › Approvals to countersign.
`approver_unmapped`	403	No person in this org matches that Slack account. Invite them in Console › Settings › Members.
`pro_required`	403	This is part of Pro. Everything free still works; see deedglass.com/pricing.

Policy (`policy_error`)

Code	HTTP	Default message
`policy_denied`	403	Blocked by policy. The action in Console › Actions names the rule and the reason.
`approval_required`	403	This action needs approval. It runs once someone approves it in Console › Approvals.
`policy_unavailable`	403	Deedglass could not evaluate the policy for this action, so it did not run. An admin can check Console › Policies.
`approval_unsatisfiable`	403	No one in this org can approve this, so it did not run. Invite another admin, or allow self-countersign in Console › Settings › Approvals.
`schedule_needs_approval`	403	A scheduled action must wait for an approval. This policy allows it now, so it would run early. Add require_approval to the rule, or drop the schedule.

Rate limit (`rate_limit_error`)

Code	HTTP	Default message
`budget_exceeded`	429	This agent has used its budget for the period. It resets when the next period starts, or an admin can raise it.
`rate_limited`	429	Too many requests. Retry after the number of seconds in the Retry-After header.
`upstream_rate_limited`	429	The service is limiting requests. Wait, then send the call again.

API (`api_error`)

Code	HTTP	Default message
`connector_unavailable`	503	The connector isn’t reachable right now. Check Console › Connectors, then retry.
`upstream_error`	502	The tool returned an error. The details are on the action in Console › Actions.
`timeout`	504	The request timed out. It may have partly run, so fetch the object to see its state before you send it again.
`internal_error`	500	Something went wrong on our side. It’s logged under this request id. Retry, and share the id if it happens again.
`service_unavailable`	503	Deedglass is starting or shutting down. Retry in a few seconds.
`vault_unavailable`	503	Deedglass couldn’t open this connector’s credentials. An admin has been alerted.
`upstream_auth_failed`	502	The service refused the connector’s credentials. An admin can replace them in Console › Connectors.
`upstream_not_found`	502	The service has nothing at that address. Check the arguments.
`response_too_large`	502	The service answered with more than the connector’s max_response_bytes, so Deedglass kept none of it. The call ran.
`database_role_unsafe`	503	The connector’s database role is a superuser. Deedglass refuses to run agent SQL with it. Run deedglass connector postgres init to create deedglass_agent.
`database_not_ready`	503	Deedglass isn’t set up in this database yet. Run deedglass connector postgres init.
`stripe_livemode_detected`	502	The stripe connector is disabled. An admin has been alerted.
`upstream_approval_pending`	502	Stripe is holding this for its own approval. Deedglass can’t see whether a Stripe reviewer approves it. Check Settings › Approvals in Stripe.

CLI codes

These come from the deedglass CLI (in --json errors), not from the API.

Code	Exit
`agent_exit`	1
`anchor_missing`	1
`below_fail_under`	1
`cancelled`	1
`command_failed`	1
`config_invalid`	1, 2
`confirmation_required`	2
`connector_test_failed`	1
`console_not_built`	1
`database_ahead`	1
`database_error`	1
`database_unreachable`	1, 2
`decoder_halted`	1
`deed_unreadable`	1
`dev_only`	1
`doctor_failed`	2
`doctor_problems`	1
`dsn_unset`	2
`export_failed`	1
`failed`	1
`file_mismatch`	1
`file_unreadable`	1
`gmail_authorize_failed`	1
`init_failed`	1
`init_running`	1
`interrupted`	1
`key_exists`	1
`key_failed`	1
`key_file_write_failed`	1
`key_invalid`	1
`key_unreadable`	1
`keys_conflict`	1
`keys_file`	1
`keys_invalid`	2
`keys_missing`	2
`keys_unreachable`	2
`licence_ended`	1
`licence_file_unsafe`	1
`licence_key_inactive`	1
`licence_key_limit`	1
`licence_key_unknown`	1
`licence_keys_invalid`	1
`licence_missing`	1
`licence_mode`	1
`licence_paused`	1
`licence_signature`	1
`licence_unreachable`	1
`link_failed`	1
`listen_failed`	1
`mcp_upstream_invalid`	1
`migrate_failed`	1
`migrate_locked`	1
`migrate_permission_denied`	1
`migration_changed`	1
`migrations_pending`	1
`network_off`	1
`no_orgs`	1
`not_a_sealed_file`	2
`not_built`	2
`not_confirmed`	1
`not_control_plane`	1
`not_set_up`	1
`not_simulated`	1
`org_create_failed`	1
`org_not_found`	2
`org_required`	2
`pack_cases_failed`	1
`pack_key_unusable`	1
`pack_keys_invalid`	1
`pack_mismatch`	1
`pack_not_found`	1
`pack_target_unsafe`	1
`pack_unreadable`	1
`pack_unsigned`	1
`pack_write_failed`	1
`packs_unreachable`	1
`pending`	2
`policy_test_failed`	1
`policy_unformatted`	1
`postgres_unreachable`	1
`prune_running`	1
`replay_cancelled`	1
`replay_failed`	1
`revoke_failed`	1
`role_missing`	1
`scenario_invalid`	2
`script_expectation_failed`	1
`script_failed`	1
`script_invalid`	2
`script_unreadable`	2
`seal_key_rejected`	1
`seal_key_rotation_failed`	1
`seal_pending`	2
`seed_failed`	1
`server_too_old`	1
`server_unreachable`	1
`share_too_long`	1
`sign_failed`	1
`simulation_overlap`	1
`source_missing`	1
`start_failed`	1
`superuser_refused`	1
`undo_not_verified`	1
`unsafe_database_role`	1
`update_check_failed`	2
`webhook_failed`	1
`write_failed`	1