Error Codes

Error response format and all error codes.

Error response format

All Noirdoc API errors follow a consistent JSON envelope:

{
  "error": {
    "type": "proxy_error",
    "code": "provider_not_configured",
    "message": "No API key configured for provider 'openai'."
  }
}

Field	Description
type	Error category (e.g., proxy_error, auth_error, validation_error)
code	Machine-readable error code for programmatic handling
message	Human-readable description of what went wrong

Always check the code field when handling errors programmatically. The message may change between versions, but code values are stable.

Proxy error codes

These errors are returned by the /v1/* proxy endpoints when forwarding requests to upstream LLM providers.

provider_not_configured

HTTP status: 502

No API key has been configured for the requested provider. For example, if you send a request with an OpenAI model but your tenant has no OpenAI provider set up.

{
  "error": {
    "type": "proxy_error",
    "code": "provider_not_configured",
    "message": "No API key configured for provider 'openai'."
  }
}

Resolution: Configure the provider via PUT /portal/providers/{provider} or contact your admin.

unsupported_endpoint

HTTP status: 404

The request path is not one of the supported proxy paths. Noirdoc only forwards requests to specific upstream endpoints.

{
  "error": {
    "type": "proxy_error",
    "code": "unsupported_endpoint",
    "message": "Endpoint '/v1/embeddings' is not supported."
  }
}

Resolution: Check the supported paths and verify your request URL.

provider_unreachable

HTTP status: 502

The upstream LLM provider returned an error or could not be reached. This can happen when the provider is experiencing downtime or returns an unexpected response.

{
  "error": {
    "type": "proxy_error",
    "code": "provider_unreachable",
    "message": "Upstream provider returned HTTP 500."
  }
}

Resolution: Retry the request after a brief delay. If the problem persists, check the provider’s status page.

provider_timeout

HTTP status: 504

The upstream provider did not respond within the configured timeout period.

{
  "error": {
    "type": "proxy_error",
    "code": "provider_timeout",
    "message": "Upstream provider did not respond within 60 seconds."
  }
}

Resolution: Retry with a simpler prompt or smaller input. For long-running requests, consider using streaming.

PII and file error codes

These errors relate to Noirdoc’s pseudonymization and file handling features.

detection_error

HTTP status: 500

The PII detection engine encountered an internal error while analyzing the request text.

{
  "error": {
    "type": "proxy_error",
    "code": "detection_error",
    "message": "PII detection engine failed."
  }
}

Resolution: Retry the request. If the error persists, contact support.

file_content_not_allowed

HTTP status: 403

File processing is disabled for this tenant. The request attempted to upload or reference a file, but the tenant’s settings do not permit file handling.

{
  "error": {
    "type": "proxy_error",
    "code": "file_content_not_allowed",
    "message": "File processing is disabled for this tenant."
  }
}

Resolution: Enable file handling in tenant settings via PATCH /portal/settings or contact your admin.

file_pii_blocked

HTTP status: 403

The uploaded file contains personal data and the tenant’s file handling mode is set to block. Noirdoc refuses to forward files with detected PII in this mode.

{
  "error": {
    "type": "proxy_error",
    "code": "file_pii_blocked",
    "message": "File contains PII and file handling mode is 'block'."
  }
}

Resolution: Remove personal data from the file before uploading, or change the file handling mode to pseudonymize in your tenant settings.

file_analysis_error

HTTP status: 500

Noirdoc failed to extract or analyze the contents of an uploaded file. This can occur with corrupted files or unsupported file formats.

{
  "error": {
    "type": "proxy_error",
    "code": "file_analysis_error",
    "message": "Failed to extract content from uploaded file."
  }
}

Resolution: Verify that the file is not corrupted and is in a supported format (PDF, DOCX, images).

Standard HTTP error codes

In addition to the Noirdoc-specific codes above, the API uses standard HTTP status codes:

Status	Code	Description
401	unauthorized	Missing, invalid, or expired authentication credentials
403	forbidden	Valid credentials but insufficient permissions
404	not_found	The requested resource does not exist
422	validation_error	The request body failed validation — check required fields and types
429	rate_limited	Too many requests — wait and retry, respecting the Retry-After header

Handling errors in code

Here is a Python example showing how to handle Noirdoc errors:

import httpx

response = httpx.post(
    "https://api.noirdoc.de/v1/chat/completions",
    headers={"Authorization": "Bearer px-your-key"},
    json={
        "model": "gpt-5.4-mini",
        "messages": [{"role": "user", "content": "Hello"}]
    }
)

if response.status_code >= 400:
    error = response.json()["error"]
    code = error["code"]

    if code == "provider_not_configured":
        print("Configure your provider in the Noirdoc portal.")
    elif code == "provider_timeout":
        print("Provider timed out. Retrying...")
    elif code == "rate_limited":
        retry_after = response.headers.get("Retry-After", "60")
        print(f"Rate limited. Retry after {retry_after}s.")
    else:
        print(f"Error: {error['message']}")