AiDial Docs

#Error Responses

#Overview

AiDial has two related error surfaces:

  • Portal routes used by signed-in browser sessions. These enforce authentication, role permissions, CSRF protection where required, and tenant or project scope.
  • Direct API routes 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.

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.

#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 portal-only endpoint was called directly with an API key instead of through a portal bearer session
  • 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 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 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

#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 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