Skip to main content

Error Handling

Defines how the Air Doctor API reports error conditions and specifies the required client response. Each status code maps to a single action path to maintain consistent behavior across all integrations. Error responses use standard HTTP status codes and may include headers or body content that instruct the client on next steps.

Error Map
401 – Invalid or expired token
302 – Prerequisite not complete
405 – UI patch requirement
500 – Server exception

Error Codes and Handling Strategies​

The table defines each server response, its scenario, and the recommended client action.

Server ResponseScenarioRecommended Client Action
401 UnauthorizedCondition: The request uses an invalid or expired token. The server returns an empty body and sets the X-Forward header to the login URL.

Impact: The request cannot proceed.		Action: Obtain a valid access token. If a backend controls authentication, refresh the token and update the client. If an external system controls, authentication, redirect the user to the URL in X-Forward.
302 FoundCondition: A required step is not complete. The Location header contains the URL of another PUT endpoint. Example: the user tries to load the video call screen without camera permission.

Impact: The requested screen cannot load.		Action: Load the URL in Location. Instruct the user to grant the required permission or complete the missing step.
405 Method Not AllowedCondition: A user-specific or state-specific validation issue requires a UI update. The response uses the PATCH format and includes error and timestamp.

Impact: The UI requires correction.		Action: Read the patches object and apply each update to the active UI. Ignore the error code except for logs.
500 Internal Server ErrorCondition: The server produces an internal exception. The response body may contain plain text for diagnostic use only.

Impact: The operation cannot complete.		Action: Display a generic error message. Provide a restart option or direct the user to support channels. A retry is unlikely to succeed.

Example: Mandatory Field is Empty​

Condition​

A required field is absent from the submitted data.

When a user submits a form without a required field, the server may respond with a 405 status. The response body includes an error code and a patches object that updates the relevant field. For example, if the phone-number field is mandatory and left blank.

Server Response​

The server returns a 405 status and provides a patches object that corrects the relevant UI element.

{
  "error": "MANDATORY_FIELD_IS_EMPTY",
  "timestamp": "2025-11-10T14:23:45",
  "patches": {
    "phone-number": {
      "e": "Phone number is required."
    }
  }
}

Required Client Action​

The client applies the patch and shows the error message next to the phone-number input, which prompts the user to correct the input. The error code is textual and suitable for diagnostics logs but does not guide application flow.

Notes​

Token Expiry
A 401 status indicates an invalid token. Initiate the client token-refresh process defined in the Access Token Handling section.

Missing Prerequisites
A 302 status indicates an unmet requirement or missing prerequisite step. Examples include missing camera, microphone, or GPS permission or incomplete profile data. Always follow the Location header to the new screen.

Patch Responses
The 405 response format enables the server to provide detailed error information in context. Because the UI message patch includes the exact message, the client focuses on showing the updated elements rather than interpreting the error code.

By applying these error-handling steps, integrators maintain consistent behavior and a stable user experience..

Implementation Checklist​

  • Validate token state for each request.
  • Validate required permissions and profile fields.
  • Apply all patches from 405 responses.
  • Log error values for diagnostics.
  • Provide consistent user-facing messages.
  • Provide restart or support options for 500 responses.