Skip to content
Copyright © 2022-2026 basebox GmbH, all rights reserved.
Licensed to be used in conjunction with basebox, only.

// integration

Error handling

Applies to

Product: Cloud · Server · Interface: OpenAI-compatible API · Audience: Developer / Integrator

The errors the OpenAI-compatible API returns – invalid key, unknown model, context too large, timeout –, what they mean and how a client should react.

The errors at a glance

HTTP status Meaning Typical cause Client behaviour
400 Bad Request Malformed request Invalid JSON, model or messages missing, invalid role (human instead of user) Do not retry; fix the request
401 Unauthorized Authentication failed "Bearer " missing, key wrong or deleted Do not retry; check key and headers, request a new key from the administrator if needed
403 Forbidden Not permitted Licence does not cover the API, wrong X-Realm, organisation not entitled Do not retry; check realm, contact the administrator
404 Not Found Endpoint or model unknown Wrong path (/api/v1/… instead of /v1/…), model identifier misspelled Do not retry; check path, query /v1/models
Context too large The request exceeds what the model can hold Message history too long, large embedded documents Shorten input: summarise history, split documents
Timeout The request took too long Very long answer, high reasoning effort, overloaded inference Retry with backoff; use streaming; set an output limit
500 / 502 / 503 Server error Inference endpoint unreachable, internal error Retry with exponential backoff (bounded); then support

The exact message texts for "model unknown", "request too large" and "timeout" are worded so that they can be shown to users.

The error format

Errors arrive as a JSON body in the OpenAI-compatible schema with an error object (message, type, possibly code). Always read the body – even for status codes you recognise; the message names the specific reason.

Messages by error type

The error message names the cause (since basebox 1.8):

  • An invalid API key returns an authentication error.
  • An unknown model, a timeout or a request that is too large each return a message of their own.

Retrying – the right way

Retry: timeouts, 5xx errors, broken streams. Exponential backoff (e.g. 1 s, 2 s, 4 s, 8 s), at most 3–5 attempts, with a random component (jitter) so many clients do not retry simultaneously.

Do not retry: 400, 401, 403, 404, context too large. The request will fail the same way the second time. Fix the cause.

Idempotency: a chat completion has no side effects; retrying is safe. With tool calling that changes something in your systems, check before retrying whether the action has already been performed.

Avoiding context too large

Every model has a context size (see Version Info in the interface). Your request – system message, the entire history, attachments and the expected answer – has to fit into it.

  • Keep the history short: summarise older turns instead of sending them in full.
  • Split documents and process them section by section.
  • Set max_tokens so the answer does not blow through the remaining space.
  • For large document collections, an app with a knowledge base is the better approach than embedding in prompts – see What is RAG?

Streaming errors

Before the first chunk you receive normal HTTP errors. After that, an error shows as a broken stream without [DONE] – treat it as an incomplete answer and retry with backoff. Details: Streaming.

Explaining errors to users

Never show the raw token or internal details. Sensible mapping:

Error Message for users
401 / 403 "The connection to basebox is not authorised. Please contact your administrator."
Context too large "The request is too large. Shorten the text or start a new conversation."
Timeout / 5xx "basebox is not responding at the moment. Please try again shortly."
Model unknown "The selected model is not available." – and reload /v1/models internally

Troubleshooting checklist

  1. Check headers: Authorization: Bearer <token>, Content-Type: application/json, X-Realm.
  2. Validate the JSON; roles only system, user, assistant, tool.
  3. Query /v1/models – does the model exist spelled exactly like that?
  4. Check the path: /v1/chat/completions, not /api/v1/….
  5. Execute the same request in Swagger UI (/v1/api/docs) – does it fail there too?
  6. For 5xx: note the time and contact support with the request (without the token) and the error response. On basebox Server the Platform Operator checks the aisrv logs and the inference endpoint.

Next step: Streaming · Troubleshooting in the user guide

Need help? Contact support