# Errors

Every Public v1 failure uses the same top-level shape. Parse the `error` object
for client behavior and retain `meta.requestId` when asking for support.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid.",
    "retryable": false,
    "details": [
      {
        "field": "query.username",
        "code": "invalid_format",
        "message": "Use a valid Profile username."
      }
    ]
  },
  "meta": {
    "requestId": "request-example"
  }
}
```

* `code` is a stable machine-readable value. Branch on it rather than
  matching `message` text.
* `message` is a human-readable summary and can change without changing the
  meaning of the response.
* `retryable` tells the client whether repeating the request may succeed.
* `details` identifies individual validation problems when available.
* `meta.requestId` correlates the failure with EnvoAPI diagnostics. It is also
  returned in the `X-Request-Id` header.

## HTTP status codes

An operation's generated reference is authoritative for the statuses it can
return. Authenticated lookup operations use these common meanings:

| Status | Meaning                                                    | What to do                                                                              |
| ------ | ---------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `400`  | Invalid request shape or value                             | Correct the parameters; do not retry unchanged.                                         |
| `401`  | Invalid or inactive API Key                                | Correct or rotate the credential.                                                       |
| `402`  | Insufficient Available Credits                             | Add Credits or wait for a grant before retrying.                                        |
| `403`  | The Account is suspended or lacks access                   | Resolve the Account or access state.                                                    |
| `404`  | The requested public resource was not found                | Correct the selector or treat it as absent.                                             |
| `405`  | A known lookup route used a method other than `GET`        | Use the method in the operation reference.                                              |
| `406`  | The requested representation is not acceptable             | Request JSON using a supported `Accept` value.                                          |
| `415`  | The declared media type is unsupported                     | Remove the body or use the documented media type.                                       |
| `429`  | The Account's rolling lookup limit was exceeded            | Honor `Retry-After`; see [Rate limits](https://docs.envoapi.com/guides/rate-limits.md). |
| `500`  | Internal failure or bounded response serialization failure | Retry only when `error.retryable` is `true`.                                            |
| `502`  | An upstream dependency returned an unusable response       | Retry with bounded backoff.                                                             |
| `503`  | Lookup is temporarily unavailable                          | Follow `error.retryable` and `Retry-After` when present.                                |
| `504`  | The lookup deadline was exhausted                          | Retry with bounded backoff.                                                             |

## Handle failures safely

Check the HTTP status before interpreting a success body. For a failed request,
branch on `error.code` and `error.retryable`; do not classify a failure by its
message alone. Bound both the number of retries and total elapsed time, and
honor `Retry-After` whenever it is present.

Do not retry validation, authentication, authorization, credit, or not-found
failures unchanged. A retry is another Lookup Request: it consumes an
account-wide rate-limit slot and can incur a Lookup Cost if admitted.

Record the request ID, operation, status, and stable code. Redact API Keys,
Lookup Inputs, raw profile data, and sensitive query parameters from logs and
error reports. See [Authentication](https://docs.envoapi.com/guides/authentication.md) for credential safety.

[Documentation index](https://docs.envoapi.com/llms.txt) · [All endpoints](https://docs.envoapi.com/api/index.md)