Errors

All errors return application/problem+json (RFC 9457 Problem Details) with a consistent shape.

{
  "type": "https://docs.xavigate.com/errors/insufficient_scope",
  "title": "API key lacks required scope",
  "status": 403,
  "detail": "This action requires the 'nature:write' scope.",
  "request_id": "req_abc123",
  "error_code": "insufficient_scope",
  "error_type": "authorization_error",
  "docs_url": "https://docs.xavigate.com/errors/insufficient_scope"
}

---

Error object fields

Field	Type	Description
type	URI	Unique error type URL — links to this page
title	string	Human-readable error summary
status	integer	HTTP status code
detail	string	Specific detail about this instance of the error
request_id	string	Unique request identifier — include in support requests
error_code	string	Machine-readable code for your error handling
error_type	string	Broad category (see below)
docs_url	URI	Direct link to error documentation
errors	array	Validation errors (present on 400 responses with field failures)

---

Error types

error_type	Meaning
authentication_error	Key missing, malformed, revoked, or not found
authorization_error	Key valid but insufficient scope for this operation
consent_error	Subject lacks consent for the requested product
invalid_request	Request body or parameters are invalid
rate_limit_error	Too many requests; back off and retry
service_error	Unexpected server error; Xavigate is investigating

---

Error codes

Code	Status	Description
unauthenticated	401	No valid API key provided
insufficient_scope	403	Key lacks required scope
insufficient_consent	403	Subject has not consented to this product
not_found	404	Resource does not exist in your account
invalid_request	400	Request body or parameters are invalid
idempotency_key_in_use	409	A request with this key is already processing
rate_limit_exceeded	429	Too many requests — see Retry-After header
internal_error	500	Unexpected server error

---

Validation errors

400 responses include a top-level errors array when multiple fields failed validation:

{
  "type": "https://docs.xavigate.com/errors/invalid_request",
  "title": "The request was invalid",
  "status": 400,
  "request_id": "req_def456",
  "error_code": "invalid_request",
  "error_type": "invalid_request",
  "errors": [
    { "field": "consent_artifact.consented_at", "code": "required", "detail": "This field is required" },
    { "field": "consent_artifact.ui_snapshot_hash", "code": "required", "detail": "This field is required" }
  ]
}

---

Handling errors in code

TypeScript

import { XavigateError } from '@xavigate/node';

try {
  const subject = await client.nature.subjects.create({ ... });
} catch (err) {
  if (err instanceof XavigateError) {
    console.error(err.error_code);   // 'insufficient_scope'
    console.error(err.request_id);  // 'req_abc123' — use in support requests
    console.error(err.status);      // 403
  }
}

Python

from xavigate import XavigateError

try:
    subject = client.nature.subjects.create(...)
except XavigateError as e:
    print(e.error_code)   # 'insufficient_scope'
    print(e.request_id)   # 'req_abc123' — use in support requests
    print(e.status)       # 403

Always log request_id

Every error includes a request_id. Log it and include it in any support request. It's the fastest way to diagnose a problem.