Error Codes

Error response format

All GOVERN API errors use a consistent JSON structure:

{
  "error": {
    "type": "validation_error",
    "message": "The 'model' field is required",
    "code": "MISSING_REQUIRED_FIELD",
    "param": "model",
    "request_id": "req_01HXYZ"
  }
}

Field	Description
`type`	Error category (see below)
`message`	Human-readable description
`code`	Machine-readable error code
`param`	Field that caused the error (validation errors)
`request_id`	Include this when contacting support

HTTP status codes

Status	Meaning
200	Success
202	Accepted (async operations)
400	Bad request — invalid input
401	Unauthorized — invalid or missing auth
403	Forbidden — insufficient permissions
404	Not found
409	Conflict — duplicate resource
422	Unprocessable — passed validation, blocked by policy
429	Rate limit exceeded
500	Internal server error
503	Service unavailable (maintenance)

Error types and codes

Authentication errors (401)

Code	Message
`INVALID_API_KEY`	The API key provided is invalid
`EXPIRED_API_KEY`	The API key has expired
`MISSING_AUTH`	No authorization header provided
`TOKEN_EXPIRED`	JWT has expired
`INVALID_TOKEN`	JWT signature verification failed

Authorization errors (403)

Code	Message
`INSUFFICIENT_PERMISSIONS`	API key does not have required scope
`IP_NOT_ALLOWED`	Request from IP not in allowlist
`ORG_SUSPENDED`	Organization account is suspended
`PLAN_LIMIT_EXCEEDED`	Feature not available on current plan

Validation errors (400)

Code	Message
`MISSING_REQUIRED_FIELD`	Required field is missing
`INVALID_FIELD_TYPE`	Field has wrong type
`INVALID_ENUM_VALUE`	Field value not in allowed list
`FIELD_TOO_LONG`	Field exceeds maximum length
`INVALID_JSON`	Request body is not valid JSON

Policy violations (422)

Code	Message
`GOVERN_POLICY_VIOLATION`	Inference blocked by governance policy
`BUDGET_EXCEEDED`	Hourly token or spend budget exhausted

Rate limit errors (429)

Code	Message
`RATE_LIMIT_EXCEEDED`	Too many requests — see Retry-After header
`BURST_LIMIT_EXCEEDED`	Burst capacity exceeded

Server errors (500)

Code	Message
`INTERNAL_ERROR`	Unexpected server error
`SCORING_FAILED`	Assessment could not be completed
`UPSTREAM_ERROR`	Error communicating with scoring backend

SDK error handling

The TypeScript SDK exposes typed error classes:

import {
  GovernError,
  GovernAuthError,
  GovernRateLimitError,
  GovernValidationError,
  GovernPolicyViolationError,
} from '@archetypal-ai/govern';

try {
  const result = await govern.assess(input);
} catch (error) {
  if (error instanceof GovernAuthError) {
    // 401/403 — check API key
    console.error('Auth error:', error.code);
  } else if (error instanceof GovernRateLimitError) {
    // 429 — back off
    await sleep(error.retryAfterMs);
  } else if (error instanceof GovernValidationError) {
    // 400 — fix the input
    console.error('Validation error on field:', error.param);
  } else if (error instanceof GovernPolicyViolationError) {
    // 422 — inference blocked by policy
    console.error('Policy violations:', error.violations);
  } else if (error instanceof GovernError) {
    // Other GOVERN error
    console.error('GOVERN error:', error.requestId);
  }
}

Getting support

When contacting support, always include the request_id from the error response. This allows our team to look up the full request trace.

Email: support@archetypal.ai Dashboard: govern.archetypal.ai/support Status page: status.govern.archetypal.ai