> For the complete documentation index, see [llms.txt](https://docs.themochi.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.themochi.app/troubleshooting-and-safety/errors.md).

# Fix an API error

An HTTP **status code** is the three-digit result of a request. Start with that code. Also keep the response `X-Request-ID`, which lets Mochi support find the request without seeing its private data.

| Status | What it usually means                                                                | First action                                                                    |
| ------ | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `400`  | A field or required header is missing or invalid.                                    | Correct the request. Do not retry it unchanged.                                 |
| `401`  | Authentication is missing, invalid, expired, or revoked.                             | Check the connection or secret-manager binding without printing the credential. |
| `403`  | The connection lacks a required scope or role.                                       | Compare the requested action with the approved permissions.                     |
| `404`  | The resource does not exist, belongs to another organization, or is not enabled.     | Check non-secret IDs and availability. Do not try nearby IDs.                   |
| `409`  | Another matching request is running, or the current state conflicts with the change. | Stop and follow the operation's idempotency guidance.                           |
| `429`  | The request rate is too high.                                                        | Wait for `Retry-After`, then retry with a limit on attempts.                    |
| `5xx`  | Mochi or a provider had a temporary failure.                                         | Retry reads with a limit; do not guess whether a write is safe to repeat.       |

For a step-by-step decision path covering API keys, OAuth, MCP, conflicts, and escalation, see [Troubleshoot API requests](/troubleshooting-and-safety/diagnose-api-failures.md).

Confirm the current response schemas in the [canonical OpenAPI contract](https://openapi.gitbook.com/o/bpgVa93BfrzaqXzuggv8/spec/mochi-api.json).

## Error response formats

Most endpoints return this format:

```json
{
  "message": "Validation error",
  "extra": {
    "fields": {
      "field_name": ["A safe validation message."]
    }
  }
}
```

Some team and flow operations return a typed format:

```json
{
  "error": {
    "type": "machine_readable_type",
    "message": "A safe error message.",
    "request_id": "opaque-request-id"
  }
}
```

An integration must handle both documented formats during the initial v1 rollout. Make decisions from the HTTP status and, when present, the typed error value. Do not make decisions from human-readable wording.

Error messages intentionally omit stored message text, contact values, credentials, and provider payloads.