Error Reference

When an API request fails, ioZen returns a structured error response with a machine-readable error code.

Error Response Format

All error responses follow the same envelope:

{
  "success": false,
  "error": {
    "code": "authentication_required",
    "message": "Missing or invalid API key",
    "details": {}
  }
}

Field	Type	Description
`code`	string	Machine-readable error code (see table below)
`message`	string	Human-readable description
`details`	object	Additional context (varies by error code, may be omitted)

Use the code field for programmatic error handling — the message field may change without notice.

Error Codes

Code	HTTP Status	Description	Details
`authentication_required`	401	Missing or invalid API key	—
`insufficient_scopes`	403	API key lacks required scopes	`required`, `granted`
`feature_not_available`	403	API access not available on current plan	`feature`
`workspace_archived`	403	Workspace has been archived	—
`resource_not_found`	404	Requested resource does not exist or belongs to another workspace	`resource`
`validation_failed`	400	Request body or parameters failed validation	`issues` (array)
`rate_limit_exceeded`	429	Too many requests	`retry_after` (seconds)
`plan_limit_exceeded`	429	Monthly resource limit reached (e.g., submissions)	`resource`, `current`, `max`
`idempotency_conflict`	409	Idempotency key already used with a different request body	—
`internal_error`	500	Unexpected server error	—

HTTP Status Codes

Status	Meaning
`200`	Success
`400`	Bad Request — validation failed
`401`	Unauthorized — authentication required
`403`	Forbidden — insufficient scopes, feature not available, or workspace archived
`404`	Not Found — resource does not exist (or belongs to another workspace)
`409`	Conflict — idempotency conflict
`429`	Too Many Requests — rate limit or plan limit exceeded
`500`	Internal Server Error

Common Troubleshooting

401 — Authentication Required

Check these in order:

Ensure the Authorization header is present and formatted correctly: Authorization: Bearer iozen_live_...
Verify the key starts with iozen_live_ — test keys (iozen_test_) are not yet supported
Check that the API key hasn't been revoked in Workspace Settings → API Keys
If the key has an expiration date, verify it hasn't expired

403 — Insufficient Scopes

The details field tells you exactly which scopes are required and which your key has:

{
  "error": {
    "code": "insufficient_scopes",
    "message": "API key lacks required scopes for this endpoint",
    "details": {
      "required": ["read:submissions"],
      "granted": ["read:intake-bots"]
    }
  }
}

Create a new API key with the needed scopes. You cannot add scopes to an existing key.

403 — Feature Not Available

Your workspace's plan doesn't include API access. API keys are available on Pro and Business plans. Upgrade from Workspace Settings → Billing.

404 — Resource Not Found

This means either:

The resource ID doesn't exist
The resource belongs to a different workspace than your API key's workspace

The API intentionally returns 404 (not 403) for cross-workspace access to prevent resource enumeration.

429 — Rate Limit Exceeded

Check the retry_after value in the error details and wait before retrying:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "details": {
      "retry_after": 12
    }
  }
}

See the Rate Limits guide for retry strategies and plan limits.

429 — Plan Limit Exceeded

Distinct from rate limiting, this means you've hit a monthly resource quota (e.g., maximum submissions per month):

{
  "error": {
    "code": "plan_limit_exceeded",
    "message": "Monthly submissions limit reached (500/500)",
    "details": {
      "resource": "submissions",
      "current": 500,
      "max": 500
    }
  }
}

Upgrade your plan or wait for the next billing cycle.

You sent a request with an Idempotency-Key header that was previously used with a different request body. Each idempotency key must always be paired with the same request body. Use a new key for different requests.

500 — Internal Error

In production, internal error messages are sanitized for security — you'll see "An internal error occurred" without implementation details. Include the X-Request-Id header value from the response when contacting hello@iozen.ai for investigation.