# Error Handling Find the causes of Context API errors and implement default behavior and a retry policy. Source: https://cue.airbridge.io/docs/en/reference/errors Language: en Updated: 2026-10-15 Your service needs default behavior that shows the existing screen or uses the default message when a Context API call fails. Handling successful responses, API errors, and timeouts separately and recording errors helps identify their causes. ## Read an error response A Context API error response contains `requestId` and `error`. The following HTTP `404` response indicates that an identifier mapping or prediction data was not found. ```json { "requestId": "01915c8e-7a12-7d3f-8b2a-1f2e3d4c5b6a", "error": { "code": "CONTEXT_DATA_NOT_FOUND", "message": "Context identifier or features were not found.", "retryable": false } } ``` The following fields help identify the error and decide how to handle it. | Field | How to use it | | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `requestId` | Include it in error logs and support requests so the call can be identified. | | `error.code` | Use it to classify the error in your application. | | `error.message` | Read it as an explanation of the error. Do not compare message strings to decide how your application behaves. | | `error.retryable` | When `true`, decide whether to retry. If you retry, increase the delay between attempts and limit the number of attempts and total wait time. When `false`, resolve the cause before requesting again. | ## Error causes and handling The table below lists causes and handling steps by HTTP status code and error code. | HTTP status | Error code | Cause and handling | | ----------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | `INVALID_JSON` | The body cannot be parsed as JSON. Correct its syntax. | | `401` | `UNAUTHORIZED` | Authentication is missing or invalid. Check the Bearer format and the target app's SDK token. | | `404` | `CONTEXT_DATA_NOT_FOUND` | An identifier mapping or app user data required for prediction is missing. Check the token's app and the user ID. Ask your Airbridge contact to check the mapping and whether the data is ready. | | `409` | `CONTEXT_INACTIVE` | Context configuration or an active model is missing. Check that CUE is enabled for the target app. | | `409` | `IDENTIFIER_CONFLICT` | User identifier mappings conflict. Ask your Airbridge contact to check the mappings. | | `413` | `PAYLOAD_TOO_LARGE` | The request body exceeds 65,536 bytes. Please reduce its size. | | `422` | `VALIDATION_ERROR` | The request does not match the schema. Check that `Content-Type` is JSON and that the request contains exactly one non-empty ID. Remove undefined fields. | | `500` | `CONTEXT_FEATURE_INVALID` | Stored model input data is invalid. Contact Airbridge with the `requestId` instead of retrying automatically. | | `503` | `AUTHENTICATION_UNAVAILABLE` | Authentication information is temporarily unavailable. Check `error.retryable` and, if retries are allowed, wait between attempts. | | `503` | `AUTHENTICATION_STATE_INVALID` | The server's authentication configuration is invalid. Contact Airbridge instead of making repeated requests. | | `503` | `CONTEXT_UNAVAILABLE` | Data retrieval or model execution failed, or model configuration needs attention. Check `error.retryable` to decide whether to retry or contact Airbridge. | | `503` | `CONTEXT_LOG_UNAVAILABLE` | The request log could not be recorded. Check `error.retryable` to decide whether to retry. If you retry, increase the delay between attempts and limit the number of attempts and total wait time. | Retry behavior differs by error code and cause, even among `503` responses. Retry decisions must account for `error.code` and `error.retryable` as well as the HTTP status code. ## Implement default behavior and retries Default behavior and a retry policy allow app users to continue using your service when an API call fails. 1. Show the existing screen or use the default message after an error, timeout, or unreadable response. 2. If you can read the response, check `error.code` and `error.retryable`. 3. If `error.retryable` is `true`, decide whether to retry. If you retry, increase the delay between attempts and limit both the number of attempts and the total wait time. Set these limits according to how long your service can wait for a result. 4. If `error.retryable` is `false`, find and resolve the cause in the request, configuration, or data before requesting again. A timeout or network failure may prevent your client from reading the server's `error.retryable` value. Your service must show the default screen or use the default message first. Your service's policy can determine whether to retry. If you retry, increase the delay between attempts and limit the number of attempts and total wait time. `404 CONTEXT_DATA_NOT_FOUND` means that information about the app user is unavailable. It is different from a response with probability `0` or tier `low`. ## Check the path and method Context API requests must use the specified URL and the `POST` method. An incorrect URL or a different method may return a generic `404` response like the following example. Its format differs from the Context API error object, so handle it separately in your client. ```json { "error": "not found" } ``` The request URL and method are listed in the [Context API endpoint](/docs/en/reference/context-api#endpoint). Your client must also run the default behavior for non-JSON error responses, such as HTML. ## Test your setup and get help Before using CUE in your service, you must test successful responses, authentication errors, missing data, and timeouts. You must also verify that your service displays the intended screen or sends the intended message in each case. Test users and example responses let you check these behaviors without changing live data. When contacting Airbridge, include the request time and time zone, `requestId`, HTTP status code, and `error.code`. If you did not receive a `requestId`, include the URL, method, and what happened.