#Error Responses

7 min read

#Overview

AiDial has two related error surfaces:

  • Portal BFF routes used by signed-in browser sessions. These enforce authentication, role permissions, CSRF protection where required, and tenant or project scope before the portal server calls aidial_api.
  • Direct aidial_api endpoints for trusted server-to-server integrations. These use API keys or approved bearer-token flows.

Portal browser requests must not send X-API-Key. API keys are for trusted server-side integrations only.

In the portal repository, route handlers live under app/api/. Browser code calls those same-origin route handlers with the NextAuth session cookie; the route handler then forwards a server-side bearer token to aidial_api. Non-API page routes are guarded by middleware.ts, while /api/ is intentionally excluded from middleware rewriting and each API route handler enforces its own authentication, RBAC, mutation protection, and tenant or project scope.

The portal does not currently expose one global JSON error envelope for every route. Route handlers use the contract for their surface:

  • Upstream aidial_api transport errors usually return code, category, message, message_key, and retryable.
  • Security-baseline settings, billing, and protected mutation routes usually return { "error": { "code", "message", "message_key", "request_id", "details" } }.
  • Some legacy calls, compliance, analytics, and support routes return route-specific flat or nested envelopes.

Always check the endpoint-specific contract before depending on response body fields. The HTTP status and machine-readable code are the stable parts to inspect first.

#Required Portal Runtime Configuration

The portal runtime requires these values. Current code reads them as required configuration and does not provide fallback defaults. AIDIAL_API_TIMEOUT_MS must be a positive number.

  • NEXTAUTH_SECRET
  • NEXTAUTH_URL
  • AIDIAL_API_BASE_URL
  • AIDIAL_API_TIMEOUT_MS
  • ZITADEL_ISSUER
  • ZITADEL_CLIENT_ID
  • ZITADEL_CLIENT_SECRET

#Common Error Codes

#400 Bad Request or 422 Validation Failed

What it means: The request payload, query string, or route-specific state failed validation.

Common causes:

  • A required field is missing or empty
  • A query parameter has an unsupported value
  • JSON could not be parsed
  • An upstream aidial_api validation response was normalised by the portal BFF

What to do:

  • Check any field_errors, details, or validation-specific response fields
  • Confirm IDs, pagination, date filters, and request body fields match the endpoint contract
  • For mutating portal routes, retry only after fixing the request body or CSRF proof

#401 Unauthorised

What it means: The request did not include valid authentication credentials.

Common causes:

  • Portal session cookie is missing, invalid, or expired
  • The portal server-side session is missing the bearer access token or required session claims
  • A direct aidial_api request did not include X-API-Key or Authorization: Bearer <token>
  • The API key is invalid, expired, or revoked
  • The bearer token is expired, malformed, or uses the wrong scheme

What to do:

  • For portal UI or BFF routes, sign in again through the portal
  • For direct aidial_api integrations, send the API key server-side in X-API-Key
  • Do not add X-API-Key to browser requests or portal route calls
  • If the error persists, contact your administrator to verify session, role, or API key status

#403 Forbidden or Security Policy Rejected

What it means: Authentication was present, but the request failed a route-specific security check.

Common causes:

  • Missing or invalid CSRF token on a mutating portal route
  • Session cookie policy violation detected on an auth route
  • IP allowlist restriction on a tenant-scoped request
  • A direct aidial_api endpoint requires a different auth mode or stronger scope

What to do:

  • For portal UI actions, refresh the page and retry so the CSRF cookie can be reissued
  • Confirm you are using the portal route handler for browser-originated actions
  • For direct integrations, check whether the endpoint requires API-key auth, bearer auth, or an admin scope
  • Contact your administrator if an IP allowlist restriction is unexpected

#404 Not Found

What it means: The resource was not found, or the authenticated actor is not allowed to know whether it exists.

Important: AiDial uses non-enumerating 404 responses for out-of-scope tenant, project, route, MFA, and role cases. This is deliberate. The portal and API should not reveal whether a resource exists when the actor does not have access.

Common causes:

  • The resource identifier is wrong
  • The resource belongs to a different tenant or project than your session or API key scope
  • Your role cannot access the requested page, BFF route, setting, call, billing record, or admin surface
  • A protected non-API page route is not in the middleware permission map
  • A bearer-authenticated session has no active portal assignment for the target
  • A mandatory-MFA session attempted a protected route before MFA was satisfied

What to do:

  • Verify the resource identifier, tenant, project, and endpoint path
  • Confirm that your portal role has access to the relevant surface
  • For partner or multi-project users, include the required scoped client_id or project_id only when the route contract allows it
  • If accessing settings or session endpoints, use portal authentication through the BFF, not browser-supplied API keys

#409 Conflict, 412 Precondition Failed, or 428 Precondition Required

What it means: The request was valid, but the target state changed or a required precondition was not met.

Common causes:

  • A settings update used a stale expected_version
  • A route using If-Match received a stale revision or missing precondition
  • A lifecycle or status transition conflicts with current service state
  • A required published/draft state is missing

What to do:

  • Refresh the page or reload the resource
  • Reapply your change against the latest version
  • Do not retry blindly if the endpoint requires an explicit expected version or precondition

#413 Payload Too Large

What it means: The request body, generated export, transcript download, or other route-specific content exceeded a configured limit.

Common causes:

  • Uploaded or submitted content is larger than the route allows
  • A transcript, export, or generated file is too large for the requested format

What to do:

  • Reduce the request size or choose a smaller export scope
  • Use an alternate route-supported format when the endpoint offers one
  • Do not retry the same oversized request unchanged

#429 Too Many Requests

What it means: A portal or service rate limit was reached.

Common causes:

  • Too many settings mutations, billing requests, comments, exports, downloads, or session lifecycle calls in a short period
  • Upstream aidial_api returned a throttling response

What to do:

  • Wait before retrying
  • Honour a Retry-After header when it is present
  • Some portal envelopes include retry timing as retry_after_ms or details.retry_after_seconds; use the route-specific field when present

#500 Internal Server Error or 503 Service Unavailable

What it means: The portal or aidial_api hit an unexpected error or a required dependency is unavailable.

Common causes:

  • A required AiDial service is unavailable or timed out
  • An upstream response failed contract validation
  • A required portal runtime configuration value is missing or invalid
  • A billing provider, session lifecycle service, or routed data dependency is unavailable

What to do:

  • Retry transient 503 responses with backoff
  • Check GET /api/health for the portal and GET /v1/health for aidial_api
  • Contact AiDial support if the error persists or if a required configuration value is missing

#Rate Limiting

Some portal and service endpoints enforce local or upstream rate limits to protect service availability. A rate-limited response uses HTTP 429 where the route fails the request. Some session lifecycle routes degrade safely for non-rate-limit upstream failures so navigation can continue, but they still return 429 when the upstream session endpoint explicitly throttles.

#Getting Help

If you encounter persistent errors:

  1. Check your credentials - Verify your API key or portal session is valid.
  2. Check the endpoint - Use the portal or API base URL supplied by your AiDial contact.
  3. Check scope - Confirm the tenant, project, role, MFA state, and endpoint are in scope.
  4. Contact your administrator - For credential, role, API key, or IP allowlist issues.
  5. Contact AiDial support - For persistent, unexplained, or dependency-related errors.

#Next Steps