# Error Handling & Limits

When a request cannot be completed, the v2 API returns a structured error instead of the usual `Data` payload. Errors are consistent across every endpoint, so you can handle them with a single code path. This page covers the error envelope, the status codes you may encounter, rate limiting, usage quotas, and the trace identifier that helps support investigate issues.

## The Error Envelope

Error responses replace the `Data` field with an `Error` object containing a machine-readable `Code` and a human-readable `Message`.

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Validation failed"
  }
}
```

Branch on the HTTP status code and the `Code` field in your integration; show or log the `Message` for diagnostics.

Validation errors may additionally include a `Fields` array inside `Error`. Each entry names the failing `Field` and carries a human-readable `Message`, and may also carry a machine-readable `Code` together with a `Params` object holding the values the message is built from (such as a length limit). The list of field codes is documented on the `FieldError` schema in the API reference; treat any code you do not recognize by falling back to the `Message`.

The `Fields` array is purely additive: the top-level `Message` remains human-readable prose describing the failure (the field messages joined by `; ` when several fail), so an integration that reads only `Message` keeps working unchanged.

```json
{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Company exceeds maximum length of 200",
    "Fields": [
      {
        "Field": "Company",
        "Code": "TOO_LONG",
        "Message": "Company exceeds maximum length of 200",
        "Params": { "Max": 200 }
      }
    ]
  }
}
```

---

## Status Codes

| Status | Meaning | Typical cause |
|--------|---------|---------------|
| `400` | Bad Request | The request body is malformed or fails validation. |
| `401` | Unauthorized | The API key is missing, malformed, or invalid. |
| `403` | Forbidden | The key is valid but not allowed to act on the requested project, or does not carry the permission the endpoint requires. |
| `404` | Not Found | The requested resource does not exist. |
| `409` | Conflict | The request conflicts with the current state, for example a duplicate save. |
| `429` | Too Many Requests | The rate limit has been exceeded. |
| `500` | Internal Server Error | An unexpected error occurred on our side. |

> **Info**
>
> **Retry only what is safe to retry**
>
> A `429` is transient and always safe to retry after a short delay. A `500` is usually transient too, but it can also mean the request's write already completed and the failure happened afterward (for example, while sending a follow-up notification) — no endpoint in this API accepts an idempotency key, so we can't tell you which case you hit. For an endpoint whose write converges when repeated (for example, a full replacement of a value), simply retrying is safe either way. For an endpoint that would double an effect if repeated, check the resource's current state before retrying, or look for a follow-up response that confirms the earlier attempt already applied. A `400`, `401`, `403`, `404`, or `409` reflects something about the request itself, so retrying without changing it will fail again.

---

## Permission Errors

An API key may be configured with a permission set that limits which endpoints it can call. When a key is used on an endpoint outside that set, the API responds with `403 Forbidden` and the code `INSUFFICIENT_SCOPE`. The `Message` names the permission that is missing, so you can tell exactly what to grant.

```json
{
  "Error": {
    "Code": "INSUFFICIENT_SCOPE",
    "Message": "token lacks scope content.generation:write"
  }
}
```

A key that was issued without a permission set is not restricted this way and can call every endpoint it has project access to. Retrying an `INSUFFICIENT_SCOPE` response never succeeds; the permission has to be added to the key, or a key that carries it has to be used instead.

---

## Rate Limiting

Every endpoint is rate-limited. When you exceed the limit, the API responds with `429 Too Many Requests` and includes a `Retry-After` header telling you how many seconds to wait before sending another request.

```json
{
  "Error": {
    "Code": "RATE_LIMIT_EXCEEDED",
    "Message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header."
  }
}
```

> **Tip**
>
> **Back off, then retry**
>
> When you receive a `429`, pause for the number of seconds in the `Retry-After` header before retrying. Honoring this header keeps your integration well-behaved and avoids compounding the limit.

---

## Usage Quotas

In addition to rate limiting, the API may be subject to plan-level usage quotas. If you expect your volume to grow, talk to your account manager so your plan is provisioned accordingly.

---

## Tracing a Request

Every response carries an `X-Trace-ID` header that uniquely identifies the request on our side.

> **Info**
>
> **Quote the trace id when you contact support**
>
> When you report a problem to `integrations@ygo.ai`, include the `X-Trace-ID` value from the affected response. It lets our team locate the exact request and resolve the issue faster.

Need help? Reach our integration team at `integrations@ygo.ai`.
