> ## Documentation Index
> Fetch the complete documentation index at: https://docs.askactual.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Treat availability labels as authoritative. Do not present planned surfaces as live.
> The product MCP can act on Actual Jobs; the documentation MCP cannot.

# Errors

> Handle planned Actual API failures without weakening authority or retry safety.

<Warning>
  The final wire error schema and error names will ship with the API contract. This page describes
  intended categories.
</Warning>

| Category                  | Typical HTTP status | Caller action                                    |
| ------------------------- | ------------------- | ------------------------------------------------ |
| Invalid request           | `400`               | Correct the request; do not retry unchanged.     |
| Authentication failed     | `401`               | Replace or refresh credentials.                  |
| Authority missing         | `403`               | Request access or User authority; do not bypass. |
| Job not found             | `404`               | Check the ID and Account scope.                  |
| Revision conflict         | `409`               | Reload the Job and rebuild the command.          |
| Approval not consumable   | `409`               | Fetch and re-present the current proposal.       |
| Rate limited              | `429`               | Honor `Retry-After` and use bounded backoff.     |
| Transient service failure | `5xx`               | Retry safely with the original idempotency key.  |

## Unknown external outcome

An action can have been dispatched even when its response was lost. Actual represents this ambiguity as **unknown** and reconciles with the Provider. Unknown is not ordinary failure. Do not repeat the action or create a replacement Job merely because no response arrived.

Record the response request ID for support, but never log credentials or sensitive Evidence bodies.