Errors

In this guide, we will talk about what happens when something goes wrong while you work with the API. Let's look at some status codes and error types you might encounter.

You can tell if your request was successful by checking the status code when receiving an API response. If a response comes back unsuccessful, you can use the error type and error message to figure out what has gone wrong and do some rudimentary debugging (before contacting support).

Status codes

Here is a list of the different categories of status codes returned by the API. Use these to understand if a request was successful.

Name
2xx
Description
A 2xx status code indicates a successful response.
Name
4xx
Description
A 4xx status code indicates a client error — this means it's a you problem.
Name
5xx
Description
A 5xx status code indicates a server error — you won't be seeing these.

Rate limits

When you exceed the API rate limit, the API responds with 429 Too Many Requests. The response carries headers describing your current standing, and — on a 429 — why you were limited and when to retry. The exact limits depend on your account's tier.

Name
x-ratelimit-limit
Description
The maximum number of requests allowed in the reported window.
Name
x-ratelimit-remaining
Description
Requests remaining in the reported window (always 0 on a 429).
Name
x-ratelimit-reset
Description
UTC epoch seconds when the quota window resets.
Name
x-ratelimit-resource
Description
The resource bucket the request counted against (e.g. genai, content).
Name
x-ratelimit-reason
Description
Only on a 429: pacing (short burst — safe to retry shortly) or quota (hourly budget exhausted — do not auto-retry).
Name
Retry-After
Description
Only on a 429: seconds to wait before retrying (always ≥ 1).
Name
x-ratelimit-retry-ms
Description
Only on a pacing 429: the exact milliseconds to wait before retrying. Never present on a quota 429.

The official Vertesia SDKs automatically retry pacing (burst) 429s for you — sleeping for x-ratelimit-retry-ms (or Retry-After) and retrying with a bounded number of attempts. They do not retry quota 429s: an exhausted hourly budget is surfaced to your code so you can back off. Raw HTTP callers should follow the same rule by reading the headers above.

Interactions Execution Errors

Whenever an execution is unsuccessful, the API will return an error response with an error type and message. You can use this information to understand better what has gone wrong and how to fix it. Most of the error messages are pretty helpful and actionable.

After an execution error occurs, the Run status is set to failed and the execution is stopped. The error message is stored in the error field of the Run object.

Error response

{
  "code": "error",
  "message": "429 Rate limit reached for gpt-4 in organization on tokens per min.
  Limit: 10000 / min.
  Please try again in 6ms.
  Contact us through our help center at help.openai.com if you continue to have issues."
  }