Skip to content

Errors and Support

What an Error Looks Like

If Nexus rejects a request, the response contains:

  • message
  • type
  • code
  • sometimes param, when the error is tied to a specific field
  • request_id

For support, request_id is the most important field.

Common Errors

invalid_key

The key is missing, incorrect, disabled, or revoked.

Check:

  • the Authorization: Bearer <API_KEY> header;
  • the x-api-key header, if your client uses it;
  • that there are no extra spaces.

endpoint_not_allowed

Your key does not have access to the selected endpoint.

Make sure the client is configured for the intended workflow. If you need different access, contact support.

model_not_allowed

The model is not enabled for your key.

Run GET /v1/models and choose a model from the response.

unsupported_model

The model does not work on the selected endpoint.

For example, a model may be available for chat.completions but not for responses.

unsupported_endpoint

The client sent a request to an unsupported endpoint.

Use only the endpoints listed on the Supported Endpoints page.

streaming_not_supported

The client requested streaming where Nexus does not support it.

Streaming is supported for:

  • POST /v1/chat/completions;
  • POST /v1/messages;
  • POST /v1/responses;
  • POST /v1/responses/compact;
  • POST /v1beta/models/{model}:streamGenerateContent.

missing_model

The request body does not include the model field.

Add the model to the JSON request.

invalid_request_json

Nexus could not parse the JSON body.

Check the JSON syntax. If the response includes param: "body", the issue is in the request body itself.

unsupported_content_type

The request used the wrong Content-Type for this route.

JSON routes require application/json. Multipart routes require multipart/form-data.

payload_too_large

The request size exceeds the route limit.

Reduce the body, file, or base64 payload size and try again.

insufficient_balance

The current Nexus profile balance is below the request admission threshold.

Top up the balance and try again.

pricing_unavailable

Safe pricing calculation is temporarily unavailable for the selected model.

This is usually resolved on the support side. Try again later or contact support with the request_id.

duplicate_request_id

This x-request-id has already been accepted earlier for another request.

The x-request-id header is intended for end-to-end tracing of a single attempt. Generate a new x-request-id for each distinct request. For safe retries on network errors or timeouts, use the Idempotency-Key header (see Retries and idempotency).

invalid_idempotency_key

The Idempotency-Key header format is invalid.

The key must contain between 1 and 256 printable ASCII characters. Use a standard format such as UUID v4.

idempotency_in_progress

A request with this Idempotency-Key is currently being processed by the system.

Wait for the number of seconds specified in the Retry-After header (typically 1 second) and retry with the same key and request body.

idempotency_conflict

The Idempotency-Key header was already used with a different request body.

Do not reuse the same idempotency key for semantically different requests (such as a different model, prompt, or parameters). Generate a new key for each new request.

result_expired

The retention window for this Idempotency-Key has expired (more than 24 hours have passed).

The saved response payload has been purged from the cache. Generate a new Idempotency-Key to submit a new execution.

Concurrency or Rate Limit Exceeded (429)

Errors such as customer_concurrency_exceeded, customer_rate_limit_exceeded, key_concurrency_exceeded, and key_rate_limit_exceeded occur when configured limits on concurrent requests or request frequency are reached.

The response includes a Retry-After header. Wait for the specified duration and reduce request concurrency.

Service Capacity and Protection Modes (503)

Errors such as provider_capacity_exceeded, global_capacity_exceeded, queue_full, queue_timeout, start_capacity_exceeded, sse_capacity_exceeded, ws_capacity_exceeded, drain_capacity_exceeded, protection_mode_engaged, billing_protection_engaged, and server_shutting_down indicate that compute capacity is temporarily saturated or the service is reloading. start_capacity_exceeded means Nexus could not start the request in time. It is retryable, not an internal failure.

Nexus returns HTTP 503 Service Unavailable with a Retry-After header. Retry after the indicated delay using the same Idempotency-Key.

billing_finalization_failed

The request reached the final billing stage, but automatic finalization failed.

Send the request_id to support. Do not retry immediately until it is clear whether the response was already accounted for.

Service Request Error

The request did not complete successfully.

Try again later. If the issue repeats, send support the model, endpoint, time of the error, and request_id.

upstream_unavailable

Nexus cannot safely start the external request because the route is temporarily unavailable.

This is usually resolved on the service side. Try again later or contact support with the request_id.

upstream_timeout

The external request did not respond within the allowed time.

This request can usually be retried later. If timeouts keep repeating, send support the request_id.

internal_error

Internal service error.

Send the request_id to support.

When to Contact Support

Contact support if:

  • the key is active, but models do not appear;
  • the balance was topped up, but requests are still rejected;
  • the same error keeps repeating;
  • you need help with your profile, API key, or balance transfer;
  • you need an individual charge review.

Contact:

What to Include

  • request_id;
  • model;
  • endpoint;
  • approximate time of the error;
  • client or tool name.