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.

{
  "Error": {
    "Code": "VALIDATION_ERROR",
    "Message": "Request validation failed"
  }
}

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

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.
`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 and a 500 are transient and worth retrying after a short delay. A 400, 401, 403, 404, or 409 reflects something about the request itself, so retrying without changing it will fail again.

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

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.

Next Steps

Overview -- Review the base URL, paths, and response envelope.

Authentication -- Get your project API key and authenticate your requests.

Content Enrichment -- Retrieve enriched hotels, manage templates, and generate text.

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

The Error Envelope#

Status Codes#

Rate Limiting#

Usage Quotas#

Tracing a Request#

Next Steps#

The Error Envelope

Status Codes

Rate Limiting

Usage Quotas

Tracing a Request

Next Steps