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

# Error codes, response format, and handling

> Reference for Yoshi API error codes, the standard error response envelope, and code examples for handling 401, 404, 429, and 500 errors.

## Error Response Format

All errors follow a consistent envelope:

```json theme={null}
{
  "error": {
    "type": "https://api.yoshi.ai/errors/not-found",
    "code": "NOT_FOUND",
    "message": "The requested resource was not found.",
    "display_message": "We couldn't find what you're looking for.",
    "param": null,
    "retry_after": null
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-04-10T12:00:00Z"
  }
}
```

## Error Codes

| Code               | HTTP Status | Description                                      |
| ------------------ | ----------- | ------------------------------------------------ |
| `UNAUTHORIZED`     | 401         | Invalid, expired, or missing API key             |
| `NOT_FOUND`        | 404         | Resource doesn't exist or you don't have access  |
| `VALIDATION_ERROR` | 422         | Invalid request parameters (check `param` field) |
| `RATE_LIMITED`     | 429         | Too many requests (check `retry_after` field)    |
| `INTERNAL_ERROR`   | 500         | Something went wrong on our end                  |

## Error Fields

| Field             | Type             | Description                                                                                          |
| ----------------- | ---------------- | ---------------------------------------------------------------------------------------------------- |
| `type`            | `string`         | Stable URI for this error type (inspired by [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html)) |
| `code`            | `string`         | Machine-readable error code for programmatic handling                                                |
| `message`         | `string`         | Developer-facing explanation with details                                                            |
| `display_message` | `string \| null` | Safe to show to end users in a UI                                                                    |
| `param`           | `string \| null` | Which request parameter caused a validation error                                                    |
| `retry_after`     | `number \| null` | Seconds until you can retry (only on `RATE_LIMITED`)                                                 |

## Handling Errors

<CodeGroup>
  ```python Python theme={null}
  import httpx

  response = httpx.get(
      "https://api.yoshi.ai/accounts",
      headers={"Authorization": "Bearer yoshi_YOUR_KEY"},
  )

  if response.status_code == 200:
      data = response.json()["data"]
  elif response.status_code == 429:
      error = response.json()["error"]
      retry_after = error["retry_after"]
      print(f"Rate limited. Retry after {retry_after} seconds.")
  elif response.status_code == 401:
      print("Invalid API key.")
  else:
      error = response.json()["error"]
      print(f"Error: {error['code']} - {error['message']}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.yoshi.ai/accounts", {
    headers: { Authorization: "Bearer yoshi_YOUR_KEY" },
  });

  if (response.ok) {
    const { data } = await response.json();
  } else {
    const { error } = await response.json();
    if (error.code === "RATE_LIMITED") {
      console.log(`Retry after ${error.retry_after} seconds`);
    } else {
      console.error(`${error.code}: ${error.message}`);
    }
  }
  ```
</CodeGroup>

## Request IDs

Every response includes a `request_id` in the `meta` object and as an `X-Request-Id` response header. Include this when contacting support about a specific request.

```bash theme={null}
curl -v https://api.yoshi.ai/accounts \
  -H "Authorization: Bearer yoshi_YOUR_KEY" 2>&1 | grep X-Request-Id
# < X-Request-Id: req_a1b2c3d4-e5f6-7890-abcd-ef1234567890
```