API docs
Book a demo

General

Error Handling & Limits

Page

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.

{
  "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.

{
  "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.

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.

{
  "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.

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

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.

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