Errors

All error responses follow a consistent JSON format.

Error response format

{
  "error": "Human-readable error message",
  "details": [ /* optional — Zod issues for 422 responses */ ]
}

• error is always a string.
• details is optional. For validation errors (422), it is an array of Zod issues describing each invalid field. For other errors it may be an object with additional debugging context, or omitted entirely.

Validation error example

// 422
{
  "error": "Validation failed",
  "details": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "undefined",
      "path": ["customer_email"],
      "message": "Required"
    }
  ]
}

HTTP status codes

Code	Meaning	When it happens
400	Bad Request	Invalid JSON, missing required fields, validation errors
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid auth but insufficient scope
404	Not Found	Resource doesn't exist or is outside your org scope
409	Conflict	Duplicate resource (e.g., vault already has authoritative copy)
422	Unprocessable Entity	Valid JSON but semantically incorrect (e.g., voiding a completed envelope)
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error

Common error examples

Missing authentication

// 401
{
  "error": "API key is required"
}

Insufficient scope

// 403
{
  "error": "Missing required scope: vault:read"
}

Envelope not found

// 404
{
  "error": "Envelope not found"
}

Vault single-copy conflict

// 409
{
  "error": "Authoritative copy already exists for this envelope",
  "details": {
    "vault_file_path": "ucc-vault/org_123/env_abc/signed.pdf"
  }
}

Invalid envelope transition

// 422
{
  "error": "Cannot void envelope with status: completed"
}

Rate limit exceeded

// 429
{
  "error": "Rate limit exceeded",
  "details": {
    "retry_after": 42
  }
}

Debugging

Every response includes an X-Request-Id header. Include this ID when contacting support:

X-Request-Id: req_a1b2c3d4-e5f6-7890-abcd-ef0123456789