Skip to main content
Classify RunBridge AI errors as request validation problems, authentication problems, path mistakes, or retryable service failures. Use HTTP status, error.code, and error.message to decide whether to fix the request or retry it.

​
Quick triage

For an image request that returned a task ID, retrieve the existing task after a timeout. Repeating a creation request can generate another image and incur another charge. If you have no task ID, keep the request ID and timestamp for support before submitting it again.

​
Error envelope

Many RunBridge AI failures use an error body like this:
Some responses leave code empty. When the status is 500, treat error.code and error.message as the deciding signal.

​
400 Bad Request

A 400 usually means the request body failed validation before the request could be processed normally. Common causes:
  • Missing required fields such as model
  • Invalid JSON shape
  • Sending a field with the wrong type
  • Reusing model-specific parameters that the selected endpoint does not accept
Start from a minimal known-good request, then add optional fields back one by one. Compare the payload against the endpoint schema in the API reference. Use a minimal request like this:
Replace your-model-id with any current model ID from the RunBridge AI Models page. Do not assume every malformed chat request returns 400. Missing required chat fields such as messages can also surface as 500 with error.code: invalid_request.

​
500 Internal Server Error

Most 500 responses indicate a service failure. For Chat Completions, some malformed requests can also surface as 500 while still carrying error.code: invalid_request. One example is a request that omits messages:
If a 500 response has error.code: invalid_request, treat it as a request problem:
  1. Fix the request body.
  2. Compare the payload against the endpoint schema.
  3. Retry only after correcting the payload.
If a 500 response does not point to an invalid request, keep the request id and use backoff.

​
401 Invalid Token

A token failure usually looks like this:
What to check:
  1. For OpenAI-compatible requests, use Authorization: Bearer $RUNBRIDGE_API_KEY. For Anthropic Messages or Gemini, follow the authentication headers in the matching API reference.
  2. Make sure your app is not loading an old key from .env, shell history, or a deployed secret store.
  3. If one key fails and another key works on the same request, treat this as a token issue, not an endpoint issue.

​
403 Forbidden

403 is most often one of these situations:
  • The request is blocked by a platform-side rule such as WAF filtering
  • The token or route is not allowed to use the requested model or request shape
  • The chosen model rejects one of the advanced parameters you passed
What to do first:
  1. Retry with a very simple text request against a known-good model.
  2. Remove advanced and model-specific fields, then add them back gradually.
  3. If the response includes a request id, keep it before contacting support.

​
Wrong base URL or wrong path

On RunBridge AI, a path mistake may surface as:
  • A redirect
  • A non-JSON HTML response if your client follows redirects
  • A parsing error inside your SDK
  • A request that never reaches the API layer cleanly
Match your SDK’s base URL to its request format: Recommended checks:
  1. Confirm the base URL matches the SDK configuration in the API reference.
  2. Confirm the complete request URL matches the documented operation path.
  3. Disable automatic redirect following while debugging path problems.

​
413 Request Entity Too Large

If you see 413, treat it as a request size problem first. Common suspects are:
  • Large base64 payloads
  • Oversized image, audio, or video inputs embedded in a multimodal LLM request
  • Very large multipart or JSON bodies
What to do:
  1. Reduce or compress attached content.
  2. Split large jobs into smaller requests.
  3. Do not assume plain text length is the only cause.

​
429 Too Many Requests

Treat 429 as retryable:
  1. Use exponential backoff with jitter.
  2. Reduce burst concurrency.
  3. Keep request logging on so you can see which route and model are saturating first.
For a reusable retry pattern, see the backoff example on Chat Completions.

​
503, 504, and 524

These statuses are server-side or timeout-class failures. Practical guidance:
  • 503: service temporarily unavailable
  • 504 and 524: a request timed out
What to do:
  1. Retry with backoff.
  2. Keep the request id, endpoint, model, and timestamp.
  3. If the same failure repeats across multiple retries, contact support with that context.

​
Before you contact support

Capture these details first:
  • HTTP method
  • Endpoint path
  • Model ID
  • Sanitized request body JSON
  • Query parameters if the failing request used them
  • Exact response body if your client captured it
  • Full HTTP status
  • The exact error.message
  • Any request id
  • Approximate timestamp
  • Whether the same request works with another model or another token
If the failing route accepts file uploads, such as a GPT Image editing request, include the submitted fields and file metadata:
  • Field names and text values you sent alongside the file
  • File name, file type, and approximate file size
  • Whether the file was uploaded directly, referenced by URL, or embedded as base64
Include the sanitized request payload with your support request. For JSON requests, provide the request body JSON. For file uploads, provide the field list and file metadata.
Last modified on October 9, 2026