OpenAI & Anthropic SDK.

Point the official Python and TypeScript SDKs at the gateway, read response headers, stream server-sent events without buffering and handle gateway errors.

OpenAI SDK.

Install openai (pip install openai or npm install openai) and point base_url (https://api.noirdoc.de/v1) and api_key at your px- key; both SDKs also read OPENAI_BASE_URL and OPENAI_API_KEY from the environment with zero code changes. One client covers Chat Completions, client.responses.create (POST /v1/responses), client.embeddings.create (POST /v1/embeddings), Audio, Images and Files. Read response headers such as X-Noirdoc-Provider and X-Noirdoc-Shield via with_raw_response (Python) or .withResponse() (TypeScript).

Client, Shield header and response headers
Python
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.noirdoc.de/v1",
    api_key=os.environ["NOIRDOC_API_KEY"],
    default_headers={"X-Noirdoc-Shield": "on"},
)

# Read response headers and override Shield for one request
raw = client.chat.completions.with_raw_response.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "Check clause 4."}],
    extra_headers={"X-Noirdoc-Shield": "off"},
)
print(raw.headers.get("x-noirdoc-provider"))
res = raw.parse()
TypeScript
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.noirdoc.de/v1",
  apiKey: process.env.NOIRDOC_API_KEY,
  defaultHeaders: { "X-Noirdoc-Shield": "on" },
});

// Read response headers and override Shield for one request
const { data, response } = await client.chat.completions
  .create(
    {
      model: "qwen3.8-27b",
      messages: [{ role: "user", content: "Check clause 4." }],
    },
    { headers: { "X-Noirdoc-Shield": "off" } },
  )
  .withResponse();
console.log(response.headers.get("x-noirdoc-provider"));

X-Noirdoc-Mask remains supported as a compatible alias for X-Noirdoc-Shield. Whether the header takes effect follows the five-tier Shield precedence.

Endpoints without Shield: /v1/images/generations rejects X-Noirdoc-Shield: on (and X-Noirdoc-Mask: on) with status 403 (masking_not_supported_for_endpoint); /v1/audio/* and /v1/files reject enforced and X-Noirdoc-Mask: on and forward other requests uninspected. Use a separate client without default_headers for image generation.

Anthropic SDK.

Install anthropic (pip install anthropic) or @anthropic-ai/sdk (npm install @anthropic-ai/sdk) and set base_url to https://api.noirdoc.de without /v1, as the SDK appends /v1/messages itself. Pass your px- key via auth_token (Authorization: Bearer) or api_key (x-api-key), or set ANTHROPIC_BASE_URL alongside either ANTHROPIC_AUTH_TOKEN or ANTHROPIC_API_KEY (never set both key variables at once, or the SDK sends both headers).

Messages and token counting
Python
import os
from anthropic import Anthropic

anthropic_client = Anthropic(
    base_url="https://api.noirdoc.de",
    auth_token=os.environ["NOIRDOC_API_KEY"],
    default_headers={"X-Noirdoc-Shield": "on"},
)

count = anthropic_client.messages.count_tokens(
    model="claude-sonnet-5-5",
    messages=[{"role": "user", "content": "Check clause 4."}],
)

msg = anthropic_client.messages.create(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Check clause 4."}],
)
print(count.input_tokens, msg.content[0].text)
TypeScript
import Anthropic from "@anthropic-ai/sdk";

const anthropicClient = new Anthropic({
  baseURL: "https://api.noirdoc.de",
  authToken: process.env.NOIRDOC_API_KEY,
  defaultHeaders: { "X-Noirdoc-Shield": "on" },
});

const count = await anthropicClient.messages.countTokens({
  model: "claude-sonnet-5-5",
  messages: [{ role: "user", content: "Check clause 4." }],
});

const msg = await anthropicClient.messages.create({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Check clause 4." }],
});
console.log(count.input_tokens, msg.content);

POST /v1/messages accepts Claude models via Google Vertex AI from GET /v1/models and your own Anthropic-compatible BYOK providers (OpenAI-format models return 400 wrong_endpoint_for_model). POST /v1/messages/count_tokens skips Shield at €0.

Streaming (SSE).

With "stream": true, POST /v1/chat/completions, POST /v1/responses and POST /v1/messages deliver server-sent events (SSE) in the provider’s native format. All other endpoints (/v1/embeddings, /v1/rerank, /v1/audio/transcriptions including form field stream, /v1/audio/speech including stream_format, /v1/images/generations) reject streaming with status 400 (streaming_not_supported_for_endpoint); on endpoints without Shield, status 403 (masking_not_supported_for_endpoint) takes precedence when enforced or X-Noirdoc-Mask: on (and X-Noirdoc-Shield: on on /v1/images/generations) is active.

SSE streams with the OpenAI and Anthropic SDKs
Python
# OpenAI SDK: POST /v1/chat/completions
stream = client.chat.completions.create(
    model="qwen3.8-27b",
    messages=[{"role": "user", "content": "Draft a cover letter."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

# Anthropic SDK: POST /v1/messages
with anthropic_client.messages.stream(
    model="claude-sonnet-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Draft a cover letter."}],
) as s:
    for text in s.text_stream:
        print(text, end="", flush=True)
TypeScript
// OpenAI SDK: POST /v1/chat/completions
const stream = await client.chat.completions.create({
  model: "qwen3.8-27b",
  messages: [{ role: "user", content: "Draft a cover letter." }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

// Anthropic SDK: POST /v1/messages
const msgStream = anthropicClient.messages.stream({
  model: "claude-sonnet-5-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Draft a cover letter." }],
});
msgStream.on("text", (t) => process.stdout.write(t));
await msgStream.finalMessage();
curl
curl -N https://api.noirdoc.de/v1/chat/completions \
  -H "Authorization: Bearer $NOIRDOC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.8-27b",
    "stream": true,
    "messages": [
      {"role": "user", "content": "Draft a cover letter."}
    ]
  }'
BehaviourRule in the Noirdoc gateway
Zero-buffering Shield inspectionNoirdoc Shield inspects only the inbound request beforehand (block hits return HTTP 403 shield_violation before opening SSE) and forwards every SSE chunk and tool call immediately with zero sentence buffering. Pre-existing organisations still on legacy masking until 2026-11-30 continue to receive sentence-buffered SSE (flushed at 2,000 characters, tool arguments once complete) when <<TYPE_N>> placeholders were assigned, marked with Deprecation: true and Sunset.
stream_options.include_usageOn POST /v1/chat/completions, the gateway enables stream_options.include_usage internally for billing and strips the extra usage chunk back out unless your request explicitly set the option.
Keep-alive (: ping) & provider commentIf the provider does not return headers within 15 s, the gateway sends status 200 and an SSE comment line : ping every 15 s (SDKs and eventsource-parser ignore : lines; skip lines starting with : in custom parsers). When 200 was flushed early, the X-Noirdoc-Provider HTTP header is omitted and emitted as : provider=<slug> directly before the first data event.
TimeoutsStreaming requests ("stream": true) wait at most 600 seconds in total across all failover attempts; non-streaming requests keep the 120-second limit.
Pre-first-byte failoverBefore the first response byte, the gateway automatically fails over on network errors, 401, 402, 429 and 5xx (Failover), even after : ping comment lines. If all providers fail before status 200, the gateway returns a normal HTTP JSON error.
Mid-stream errorsOnce the stream starts, the provider stays fixed: mid-stream drops emit stream_interrupted, failures after an early 200 emit their regular code (including retry_after in seconds in the error object), and deploys waiting on a provider emit gateway_restarting with retry_after: 5. Format: /v1/chat/completions sends data: {"error": {...}} + data: [DONE] (raises APIError); /v1/responses sends event: error + data: [DONE] (yields a flat type: "error" event in the OpenAI Python SDK without raising: check it in your loop); /v1/messages sends event: error + message_stop.

Error handling and retries.

Every error response carries type, code and message (plus request_id on Anthropic routes: /v1/messages and /v1/skills always use the Anthropic format, /v1/files follows x-api-key vs Bearer, and all other routes use the OpenAI format). Always branch on code rather than message: the OpenAI SDK exposes code directly on the error, whereas the Anthropic SDK places it under error.code in the response body.

OpenAI SDK: inspect error code and provider
Python
import openai

try:
    res = client.chat.completions.create(
        model="qwen3.8-27b",
        messages=[{"role": "user", "content": "Hello"}],
    )
except openai.APIStatusError as e:
    if e.code == "provider_rejected_request":
        prov = e.response.headers.get("x-noirdoc-provider")
        print("Provider rejected:", prov, e.body["message"])
    else:
        print("Error:", e.status_code, e.code)
TypeScript
try {
  const res = await client.chat.completions.create({
    model: "qwen3.8-27b",
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (err) {
  if (!(err instanceof OpenAI.APIError)) throw err;
  if (err.code === "provider_rejected_request") {
    const prov = err.headers?.get("x-noirdoc-provider");
    console.log("Provider rejected:", prov, err.message);
  } else {
    console.log("Error:", err.status, err.code);
  }
}
Anthropic SDK: read error code from the body
Python
import anthropic

try:
    msg = anthropic_client.messages.create(
        model="claude-sonnet-5-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}],
    )
except anthropic.APIStatusError as e:
    err = e.body["error"]
    if err["code"] == "provider_rejected_request":
        prov = e.response.headers.get("x-noirdoc-provider")
        print("Provider rejected:", prov, err["message"])
    else:
        print("Error:", e.status_code, err["code"])
TypeScript
type GatewayBody = {
  error?: { type?: string; code?: string; message?: string };
};

try {
  const msg = await anthropicClient.messages.create({
    model: "claude-sonnet-5-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (err) {
  if (!(err instanceof Anthropic.APIError)) throw err;
  const body = err.error as GatewayBody | undefined;
  if (body?.error?.code === "provider_rejected_request") {
    const prov = err.headers?.get("x-noirdoc-provider");
    console.log("Provider rejected:", prov, body.error.message);
  } else {
    console.log("Error:", err.status, body?.error?.code);
  }
}

The gateway maps provider errors uniformly: capacity limits to 429 resource_exhausted and overload to 503 (529 on /v1/messages) provider_overloaded each with Retry-After, rejected requests to provider_rejected_request with the provider’s message (on BYOK routes also for provider 401, 402, 403 and 429; see Error format) and other upstream errors to 502 provider_error. Both SDKs retry status codes 408, 409, 429 and 5xx up to max_retries (default: 2, after gateway failover), honouring Retry-After up to 60 seconds and falling back to exponential backoff beyond that. Status 401 (invalid_api_key) and 402 (insufficient_credit, key_budget_exhausted) are never resolved by retrying; handle them directly in your application.

Status Code Meaning
400 wrong_endpoint_for_model The model belongs to a different endpoint family or API format than the endpoint called.
400 streaming_not_supported_for_endpoint The request asks for streaming, but the endpoint does not support it.
400 provider_rejected_request The provider itself rejected the request, for example because of an invalid parameter or a context that is too long. The response carries the provider's status code (400, 404, 409, 413, 422 or another 4xx status code except 401, 402, 403 and 429), and message contains the provider's message, shortened and sanitised, at most 500 characters. On routes with your own provider key (BYOK) the gateway also reports the provider's status codes 401, 402, 403 and 429 this way, because the key, credit and quota belong to the customer; with 429 it adds Retry-After.
401 invalid_api_key The key is missing, invalid or deactivated, or the organisation is not active.
402 insufficient_credit The organisation's credit is used up or lower than the estimated maximum cost of the request (including Noirdoc Shield, also on BYOK routes when Shield is active).
402 key_budget_exhausted This key's budget is used up for the current period or does not cover the estimated cost of the request.
403 shield_violation Noirdoc Shield blocked the request before forwarding to the provider because an active protection filter configured with block matched; message names the triggered rule (secrets, pii, ner, injection or custom).
403 masking_not_supported_for_endpoint The endpoint supports neither Noirdoc Shield nor legacy masking, yet the policy is enforced or the request sends X-Noirdoc-Mask: on (and on /v1/images/generations also X-Noirdoc-Shield: on). During the legacy masking transition until 30.11.2026, this also affects /v1/embeddings and /v1/rerank on pre-existing organisations that have not switched to Shield yet.
404 model_not_available The model ID is not available to the organisation.
429 resource_exhausted The provider reported capacity problems or exhausted credit (status code 429 or 402), even after failover across up to three providers. The response contains Retry-After with the wait in seconds.
502 stream_interrupted The provider's stream broke off or reported an error after the response had started. The error is in the stream itself, because status code 200 has already been sent by then. stream_interrupted carries no retry_after; only errors in the stream that correspond to an HTTP error with a wait carry it.
503 provider_overloaded The provider reported overload (status code 503 or 529), even after failover across up to three providers. The status code is 503 on OpenAI endpoints and 529 on /v1/messages and /v1/skills. The response contains Retry-After with the provider's value between 1 and 60 seconds, otherwise 5 seconds.
503 gateway_restarting The gateway was restarted (deployment) while the stream was still waiting for the provider's response. The error is in the running stream, because status code 200 has already been sent by then. The error object contains retry_after with 5 seconds.
504 provider_timeout The provider did not answer within the gateway's timeout. The response contains Retry-After with 10 seconds.