Error Codes

All error responses include a code field with a machine-readable error code. SDKs can react programmatically to these codes.

SDK-facing codes

These are the codes most relevant to SDK integrations:

Code	Status	Message	Fix
ADJ_VALIDATION_FAILED	400	Trace payload validation failed	Check that inputContext.prompt and outputDecision.action are present
ADJ_UNKNOWN_SCHEMA_VERSION	400	Unknown schema version	Check the X-Adjudon-Version header value
ADJ_BLOCKED_BY_POLICY	403	Decision blocked by policy	Review your active policies in the dashboard
ADJ_FLAGGED_FOR_REVIEW	202	Decision flagged for human review	Not an error — trace is queued for review
ADJ_DUPLICATE_REQUEST	409	Duplicate request	Same idempotency key used within 24 hours — treat as success
ADJ_RATE_LIMITED	429	Rate limit exceeded	Back off and retry. Check Retry-After header
ADJ_QUOTA_EXCEEDED	429	Usage quota exceeded	Upgrade plan or wait for next billing cycle
ADJ_PAYLOAD_TOO_LARGE	413	Payload too large	Reduce trace payload size (max 1MB)
ADJ_AGENT_NOT_FOUND	404	Agent not found	Check agent ID matches an existing agent
ADJ_INVALID_API_KEY	401	Invalid API Key	Check key is correct and not rotated
NO_API_KEY	401	API Key is missing	Include X-API-Key header
INVALID_API_KEY	401	Invalid API Key	Check key is correct and not rotated
ADJ_API_KEY_AGENT_SCOPE	403	API key agent scope mismatch	Key is scoped to a different agent

---

Full error code registry

Auth — JWT / Session

Code	Status	Message
UNAUTHORIZED	401	Authentication required
UNAUTHORIZED_NO_USER	401	Not authorized, user not found
NO_TOKEN	401	Not authorized, no token
TOKEN_REVOKED	401	Session has been revoked
SESSION_REVOKED	401	Session has been revoked
TOKEN_VERIFICATION_FAILED	401	Not authorized, token failed
INVALID_TOKEN	401	Invalid or expired token
INVALID_TOKEN_TYPE	401	Invalid token type
TEMP_TOKEN_EXPIRED	401	Temporary token expired
INVALID_CREDENTIALS	401	Invalid credentials
INVALID_PASSWORD	401	Incorrect password
INVALID_RESET_TOKEN	400	Invalid or expired reset token
CONFIG_ERROR	500	Server configuration error

Auth — API Keys

Code	Status	Message
NO_API_KEY	401	API Key is missing
INVALID_API_KEY	401	Invalid API Key
INVALID_API_KEY_FORMAT	401	Invalid API Key format
API_KEY_VERIFICATION_ERROR	500	Server error during API key verification
ADJ_INVALID_API_KEY	401	Invalid API Key
ADJ_API_KEY_AGENT_SCOPE	403	API key agent scope mismatch
API_KEY_AGENT_SCOPE	403	API key agent scope mismatch
API_KEY_READ_ONLY	403	API key is read-only

Auth — Organization

Code	Status	Message
ORG_NOT_FOUND	401	Organization not found
ORG_ACCESS_DENIED	403	Not a member of this organization
MISSING_ORG_ID	400	organizationId is required

Auth — Permissions

Code	Status	Message
FORBIDDEN	403	Forbidden
SUPER_ADMIN_REQUIRED	403	Super admin access required

MFA

Code	Status	Message
INVALID_2FA_CODE	401	Invalid 2FA code
MFA_ALREADY_ENABLED	400	MFA is already enabled
MFA_NOT_ENABLED	400	MFA is not enabled
MFA_NOT_INITIATED	400	MFA not initiated

SSO / OAuth

Code	Status	Message
OAUTH_ACCOUNT	400	Cannot change password for OAuth accounts
NO_OAUTH_TOKEN	401	No OAuth token found
INVALID_OAUTH_TOKEN	401	Invalid or expired OAuth token
UNSUPPORTED_PROVIDER	400	Unsupported SSO provider
SSO_NOT_CONFIGURED	404	No SSO configuration found
SSO_INIT_FAILED	500	Failed to initiate SSO

Auth — Password & Passkey

Code	Status	Message
PASSWORD_REQUIRED	400	Password is required
PASSWORD_REUSED	400	Password was used recently
EXPIRED	400	Session expired
VERIFICATION_FAILED	400	Verification failed
NO_JTI	400	Session cannot be individually revoked

Validation

Code	Status	Message
MALFORMED_JSON	400	Malformed JSON in request body
VALIDATION_ERROR	400	Validation failed
INVALID_INPUT	400	Invalid input
INVALID_IDS	400	Invalid IDs
INVALID_STATUS	400	Invalid status
INVALID_WORKSPACE_ID	400	Invalid workspace ID format
WORKSPACE_REQUIRED	400	Workspace ID is required

Trace Ingestion (ADJ_* — SDK-facing)

Code	Status	Message
ADJ_VALIDATION_FAILED	400	Trace payload validation failed
ADJ_UNKNOWN_SCHEMA_VERSION	400	Unknown schema version
ADJ_BLOCKED_BY_POLICY	403	Decision blocked by policy
ADJ_FLAGGED_FOR_REVIEW	202	Decision flagged for human review
ADJ_DUPLICATE_REQUEST	409	Duplicate request
ADJ_RATE_LIMITED	429	Rate limit exceeded
ADJ_QUOTA_EXCEEDED	429	Usage quota exceeded
ADJ_PAYLOAD_TOO_LARGE	413	Payload too large
ADJ_AGENT_NOT_FOUND	404	Agent not found
ADJ_ORGANIZATION_NOT_FOUND	401	Organization not found for this agent

Not Found

Code	Status	Message
NOT_FOUND	404	Resource not found

Conflict / Duplicate

Code	Status	Message
ALREADY_EXISTS	400	Resource already exists
ALREADY_MEMBER	400	Already a member
DUPLICATE	400	Duplicate resource
DUPLICATE_DOMAIN	409	Domain already registered
DOMAIN_CONFLICT	409	Domain already configured
ORG_NAME_TAKEN	400	Organization name taken
NAME_TAKEN	409	Name already taken

Rate Limiting / Quota

Code	Status	Message
RATE_LIMIT_EXCEEDED	429	Rate limit exceeded
USAGE_LIMIT_EXCEEDED	429	Usage limit exceeded

Feature Gate

Code	Status	Message
UNKNOWN_FEATURE	403	Unknown feature
UPGRADE_REQUIRED	403	Plan upgrade required

Operations

Code	Status	Message
INVALID_OPERATION	400	Invalid operation
TEST_FAILED	400	Test execution failed
SSRF_BLOCKED	400	Request blocked (SSRF protection)
WEBHOOK_TEST_FAILED	200	Webhook delivery failed

Workspace

Code	Status	Message
WORKSPACE_ACCESS_DENIED	403	Workspace access denied
WORKSPACE_VALIDATION_ERROR	500	Workspace validation error

Server

Code	Status	Message
INTERNAL_ERROR	500	Internal server error
SERVER_ERROR	500	Server error
REPORT_ERROR	500	Report generation failed
MAINTENANCE_MODE	503	Service temporarily unavailable