Errors

Agent error taxonomy

Every CertifiedData agent endpoint returns structured errors. Use error_code for branching, retry_after_seconds for backoff, and request_id for support correlation.

Response shape

Error envelope

{
  "ok": false,
  "error_code": "rate_limit_exceeded",
  "error": "Anonymous sandbox limit: 10 runs / 24h per IP.",
  "retry_after_seconds": 3600,
  "documentation_url": "https://certifieddata.io/agents/errors#rate_limit_exceeded",
  "request_id": "req_01HXYZ..."
}

Error codes

error_code	HTTP	Retryable	Category	Meaning	Remediation
authentication_required	401	no	Auth	No Bearer token on an authenticated route.	Add Authorization: Bearer <cdp_test_ or cdp_live_ key>.
invalid_api_key	401	no	Auth	Bearer token not recognized.	Rotate via /dashboard/api-keys; ensure prefix matches environment.
forbidden_ownership	403	no	Auth	The key's user does not own the resource.	Use a key owned by the resource's org.
plan_required	402	no	Tier	Engine or cert level gated above current plan.	Upgrade via /pricing or use a lower engine (e.g. light/gaussian).
rate_limit_exceeded	429	yes	Quota	Per-IP or per-key window exceeded.	Wait retry_after_seconds. See /agents/rate-limits.
quota_exceeded	402	maybe	Quota	Monthly plan quota exhausted.	Wait for reset or upgrade plan.
invalid_input	400	no	Validation	Zod schema rejection of request body.	Fix per details[] in response.
prompt_injection_detected	400	no	Safety	Input contained a blocked prompt pattern.	Strip system-prompt directives, URLs, HTML/script from free-text fields. See /agents/safety.
engine_not_available	400	no	Tier	Requested engine disabled on current plan.	Use a permitted engine.
cert_level_not_available	400	no	Tier	cert_level above plan entitlement.	Downgrade cert_level or upgrade plan.
policy_evaluation_failed	422	no	Commerce	Runtime policy rejected the authorization.	Inspect policy_result field; adjust quote or policy.
insufficient_funds	402	no	Commerce	Rail declined settlement.	Top up, switch rail, or reduce amount.
rail_unavailable	503	yes	Commerce	Configured rail is temporarily down.	Retry later or select alternate rail.
signature_invalid	400	no	Crypto	Verification of a submitted signature failed.	Sign with the declared key_id; check canonicalization.
challenge_expired	410	no	Crypto	Attestation nonce older than 5 minutes.	Mint a fresh challenge via POST /api/agents/:id/challenge.
challenge_already_used	409	no	Crypto	Attestation already verified.	Mint a fresh challenge.
key_revoked	410	no	Crypto	Public key has been revoked.	Register a new key via POST /api/agents/:id/keys.
artifact_not_found	404	no	Registry	cert_/scert_/rcpt_/drec_ id unknown.	Check id. Sandbox certs expire after 7 days.
sandbox_expired	410	no	Registry	Sandbox scert_ past 7-day TTL.	Generate a new sandbox cert or claim-and-upgrade before expiry.
internal_error	500	yes	Platform	Unhandled server error — already logged.	Retry with backoff. Include request_id in support requests.
dependency_unavailable	503	yes	Platform	Upstream (OpenAI, Stripe, DB) temporarily down.	Retry with exponential backoff.

Retry strategy

retryable=yes: exponential backoff, base 2s, max 30s, cap 6 attempts.
retryable=maybe: inspect context (quota vs. transient) before retrying.
retryable=no: do not retry — fix input, auth, or plan.
Honor Retry-After and retry_after_seconds when present.

Rate limits Safety model SDK Changelog OpenAPI spec