# Errors

Last updated: 2026-10-11

Read the error code and any execution evidence before deciding what to do next. A failed HTTP exchange does not prove that an Action had no effect.

## Authentication and request refusals

Data API authentication refusals identify the error in `error` and supply guidance in `message`. For other failures, use the Request's generated OpenAPI error schema. Branch on the error code rather than parsing guidance text.

HTTP execution failures also put the code in `error`. When execution evidence is available, `execution_id`, `outcome`, `failure_class`, and `remediation` are top-level fields, not nested under MCP's `details`. An indeterminate execution can return HTTP 202 with `error: "execution_indeterminate"` and `outcome: "indeterminate"`; a 2xx status alone does not establish success.

| Data API error | What to check |
| --- | --- |
| `invalid_token` | The `Authorization` header needs a valid Bearer credential. Check the key, its Project, and whether it was rotated or revoked. The response includes a `WWW-Authenticate` Bearer challenge; it does not start a browser sign-in. |
| `not_found` | Check the Request identifier against the caller's current catalog. A Request identifier that does not exist is refused. |
| `invalid_request` | Check the body against the Request's contract. For example, a Data Access Point without a subject source cannot supply a `subject`. |

These are selected refusals, not an exhaustive error inventory. The Project's generated `catalog.openapi` describes its HTTP execution error schema. See [Call an approved Request](/docs/call-an-approved-request/).

## MCP execution failures

Structured MCP tool error content uses `error: true`, `code`, and `message`, with execution evidence nested in `details` when available. The tool result is also marked `isError`. Protocol or transport failures may arrive without this structured content.

| Code | Next step |
| --- | --- |
| `api_execution_failed` | Keep `details.execution_id` and the returned diagnostic details. An authorized caller can inspect the execution record with `get_execution`. |
| `execution_indeterminate` | The effect is uncertain. Investigate the execution record and source state before deciding whether another call is safe. |
| `result_encoding_error` | Execution reached result rendering, but the result could not be encoded. For an Action, inspect the execution evidence instead of repeating the operation to recover its output. |
| `invalid_result` | The result cannot be represented as a valid table, for example populated rows without declared columns. Inspect the execution evidence and the Request's output definition. |

For `api_execution_failed`, preserve `details.failure_class`, `details.outcome`, and `details.remediation` when present. The classification is diagnostic context; it does not replace the outcome or authorize a retry.

When the MCP caller may read `get_execution`, the response can include the stored, sanitized provider reason in `details.error_message` and point to `get_execution` in `details.next_step`. That extra reason is not returned to every caller. Give the execution identifier to a Project Administrator if your identity cannot inspect it.

## Outcomes and retry decisions

- `succeeded`: the reported operation succeeded. A later rendering error does not undo its effect.
- `failed`: the operation reports definite failure. Read the error and correct its cause before considering another attempt.
- `indeterminate`: the effect cannot be confirmed. Do not automatically repeat the Action.

Ekaya does not silently repeat an ambiguous Action. The application owns retry decisions, reconciliation with the source, and any wider workflow. Keep the execution identifier, code, outcome, and available details together when investigating.

Mock responses touch no business data and prove nothing about the real operation. Do not treat a mock result as evidence that a live Request succeeds.