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/messages;
  • POST /v1/responses;
  • POST /v1/responses/compact.

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 Nexus profile does not have enough funds for the new request or for its temporary reserve.

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.

pricing_stale

The pricing entry for the model needs to be refreshed before a new request can be accepted.

Try again later or contact support.

duplicate_request_id

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

Create a new x-request-id, or remove this header if your client does not require it.

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 reach the upstream provider because of configuration or temporary availability issues.

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

upstream_timeout

The upstream provider 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 an additional API key or account access recovery;
  • you need a manual billing review.

Contact:

What to Include

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