Errors and error codes

Every error the ISMS Copilot API returns: HTTP status, OpenAI error type, code, what it means, and whether to retry.

Errors use the OpenAI error shape, so the official OpenAI SDKs raise their usual exception classes (BadRequestError, AuthenticationError, RateLimitError and so on):

{
  "error": {
    "message": "Your API credit balance is $0. Add credit (minimum $20) at https://platform.ismscopilot.com/credits to continue.",
    "type": "rate_limit_error",
    "param": null,
    "code": "insufficient_quota"
  }
}

Branch on error.code when it is set, and on the HTTP status plus error.type when it is null. Never branch on the message text: messages can change, codes do not.

Quick rule for retries

Retry?	Cases
Yes, after `Retry-After`	`429` with `rate_limit_exceeded`
Yes, with backoff	`429` with `trial_concurrency_limit`, `502`, `503`, `504`, a `429` with `code: null` (upstream provider busy), and a `401` with "API key validation failed", "Credit balance check failed" or "Usage check failed" (a check on our side)
No, fix the request	Every `400`, `404` and `413`
Never, fix the key or the account	`401` with "Missing Authorization", "Empty bearer token" or "Invalid API key"; `429` with `insufficient_quota` or `*_limit_exceeded`

The insufficient_quota response carries x-should-retry: false, so the official OpenAI Python and Node SDKs stop instead of retrying it. They do retry other 429 and 5xx responses by default.

400: invalid request

Type invalid_request_error. The param field names the part of the request at fault.

Code	`param`	Meaning	Fix
`null`	`tools`	`tools`, `tool_choice`, `functions` or `function_call` were sent. Message: "Tool / function calling is not supported in v1".	The API is a text-only subset. Do not bind tools to this model; keep a general model as your orchestrator and call this API as a plain completion. See Use the API in coding agents.
`null`	`response_format`	`response_format.type` other than `"text"` (JSON mode and structured outputs).	Ask for the shape in the prompt and parse the text yourself.
`null`	`n`	`n` above 1.	Send one request per completion.
`null`	`logprobs`	`logprobs: true`.	Not supported.
`null`	`messages`	Empty `messages`, a role other than `system`, `developer`, `user` or `assistant` (for example `tool`), a content part that is not text (images, audio), or no user or assistant message at all.	Send text content only.
`null`	`model`	`model` missing.	Pass an alias such as `isms-fast`.
`null`	`max_tokens`	Not a positive integer.	Send a positive integer or omit it.
`null`	`null`	The body is not valid JSON, or not a JSON object.	Check the serialisation.
`null`	`null`	"Streaming is not enabled for this endpoint".	Retry without `stream`; streaming is normally on.
`context_length_exceeded`	`messages`	The assembled prompt (your messages, the server prompt and the injected modules) plus the reserved output would exceed the 128,000-token window. Rejected before billing.	Pin fewer modules, shorten the messages, or lower `max_tokens`. See Models and regions.
`framework_not_found`	`ismscopilot.frameworks`	A pinned id is not in the catalog.	Use ids from `GET /v1/frameworks`.
`ismscopilot_invalid`	`ismscopilot.*`	The `ismscopilot` extension is malformed: not an object, an unknown property, an empty `frameworks` array, more than 8 pinned ids, a duplicate id, or `system` set to anything but `"none"`.	See Framework knowledge.
`ismscopilot_extension_disabled`	`ismscopilot`	The extension was sent to a deployment where it is switched off. The API refuses rather than silently ignoring it.	Remove the field, or contact us.
`trial_request_too_large`	`null`	You are on the free first-call credit and the request's estimated price is above the per-request ceiling.	Shorten the prompt or lower `max_tokens`, or add credit.

401: authentication

Type authentication_error, code: null.

Message	Meaning	Fix
`Missing Authorization: Bearer <key>`	No `Authorization` header, or not a Bearer token.	Send `Authorization: Bearer sk-isms-…`.
`Empty bearer token`	The header is there, the token is empty.	Check the environment variable is set.
`Invalid API key`	The key is unknown, revoked or mistyped.	Create a new key at platform.ismscopilot.com/keys.
`API key validation failed`, `Credit balance check failed`, `Usage check failed`	A check on our side failed while validating the key. Your key is not the problem.	Retry after a short wait. If it persists, contact us.

Account MCP tokens (pat-isms-…) are a different plane and are rejected here. See Agents.

404: not found

Type	Code	Meaning
`invalid_request_error`	`model_not_found`	The `model` is not an alias this API serves (on `POST /v1/chat/completions` and `GET /v1/models/{id}`). Valid aliases: `isms-fast`, `isms-thinking`, `isms-fast-eu`, `isms-thinking-eu`, `isms-mini`.
`not_found_error`	`null`	The route does not exist, for example `/v1/responses` or `/v1/embeddings`. Only chat completions, models and the framework catalog are served.

413: request too large

Type invalid_request_error, code request_too_large. The request body is above 10 MiB. You will usually hit context_length_exceeded long before this.

429: credit, spend caps and rate limits

Type rate_limit_error.

Code	Meaning	Fix
`insufficient_quota`	Your prepaid balance is $0 or below. Sent with `x-should-retry: false`.	Top up at platform.ismscopilot.com/credits (minimum USD 20). Retrying will not help.
`hour_limit_exceeded`, `day_limit_exceeded`, `week_limit_exceeded`, `month_limit_exceeded`	A per-key spend cap you set was reached. The message shows spent and limit.	Raise or remove the cap on the Keys page, or wait for the period to roll.
`trial_concurrency_limit`	On the free first-call credit, one request runs at a time.	Retry when the first request finishes, or add credit.
`rate_limit_exceeded`	Too many requests per minute. The message names the scope (per API key, or per client IP address). Sent with `Retry-After` and `x-ratelimit-*` headers.	Wait the `Retry-After` seconds. See Request rate limit.
`null`	The upstream model provider is rate limiting. Message: "Upstream AI provider error."	Retry with backoff.

5xx: server and upstream errors

Type api_error unless stated.

Status	Code	Meaning	Fix
`500`	`null`	"Internal server error." or "Usage tracking unavailable". The request was not completed.	Retry with backoff.
`500`	`provider_misconfigured`	A configuration fault on our side for that path.	Contact us; try another alias meanwhile.
`502`	`null`	"Upstream AI provider error." or "The model returned an empty response. Please try again."	Retry with backoff.
`503`	`trial_check_failed`	The credit check for a low balance was briefly unavailable. The request is refused rather than run unmetered.	Retry shortly.
`503`	`server_shutdown`	The server is restarting and drained your request.	Retry; another machine picks it up.
`504`	`timeout`	The request ran past 5 minutes, or the upstream sent nothing for 90 seconds.	Retry, stream long generations, or lower `max_tokens`.

Catching errors in code

import os
import openai
from openai import OpenAI

client = OpenAI(base_url="https://api.ismscopilot.com/v1", api_key=os.environ["ISMS_API_KEY"])

try:
    resp = client.chat.completions.create(
        model="isms-fast",
        messages=[{"role": "user", "content": "Which ISO 27001:2022 control covers secure coding?"}],
        extra_body={"ismscopilot": {"frameworks": ["ISO_27001"]}},
    )
except openai.RateLimitError as e:
    if e.code == "insufficient_quota":
        alert_ops("ISMS Copilot API balance is empty")  # your own alerting
    raise
except openai.BadRequestError as e:
    # framework_not_found, context_length_exceeded, tools rejected, ...
    log_bad_request(e.code, e.param)  # your own logging
    raise

Rejections before the model runs (every 400, 401, 404, 413, and the credit, spend-cap and rate-limit 429s) cost nothing.

Get an API key and first completion (common failures)
Credits, pricing, and spend limits
Framework knowledge
OpenAPI definition

Errors and error codes

On this page