Reference
Error codes
Every error code Maskflare's gateway, proxy and browser DLP return: the HTTP status, what it means and how to fix it. Each problem response links its page here.
Refusals are RFC 9457 problem documents (application/problem+json) with a stable code, a detail that says how to fix it and a type linking the code's page below. Codes that end in :something (a browser upload's file extension) are listed without the suffix.
| Code | Status | Where | Meaning |
|---|---|---|---|
| action_key_unavailable | 503 | Gateway mode, Proxy mode | A hash or format-preserving rule needs a key this deployment lacks. |
| api_key_purpose_not_allowed | 403 | Gateway mode, Proxy mode | The key's purpose (gateway, redaction, edm) doesn't cover this endpoint. |
| api_key_purpose_unsupported | 403 | Gateway mode, Proxy mode | The key has a purpose this service doesn't know. |
| batch_upload_unsupported | 422 | Gateway mode, Proxy mode | Resumable batch uploads (`/uploads`) can't be inspected. |
| browser_dlp_invalid_multipart | 403 | Browser DLP | The upload's multipart body couldn't be read. |
| browser_dlp_secret | 403 | Browser DLP | The message held a credential-shaped secret (API key, token, private key). |
| browser_dlp_unavailable | 503 | Browser DLP | The message couldn't be inspected, so it wasn't sent. |
| browser_dlp_uninspectable_upload | 403 | Browser DLP | The app uploads this kind of file where Maskflare can't check it (the suffix is the file's extension). |
| browser_dlp_unparseable_form | 403 | Browser DLP | The app's form body wasn't readable. |
| browser_dlp_unparseable_json | 403 | Browser DLP | The app's message wasn't readable JSON. |
| browser_dlp_unparseable_proto | 403 | Browser DLP | The app's binary message wasn't readable. |
| browser_dlp_unreadable_proto | 403 | Browser DLP | The app's message text wasn't valid UTF-8. |
| browser_dlp_unreadable_text_upload | 403 | Browser DLP | A text file wasn't valid text. |
| browser_dlp_unsupported_content_type | 403 | Browser DLP | The app sent a body type Maskflare can't inspect. |
| browser_dlp_unsupported_upload | 403 | Browser DLP | Maskflare can't check this kind of file. |
| browser_dlp_upload_missing_file | 403 | Browser DLP | An upload carried no file part. |
| ca_unavailable | 503 | Proxy mode | The organization's certificate authority couldn't issue a certificate. |
| console_access_required | 403 | Platform API | Members without a console role (end users) can't use the console or its API. |
| destination_not_allowed | 403 | Proxy mode | This proxy only carries AI traffic and the host isn't an inspected one. |
| deterministic_masking_unavailable | 503 | Gateway mode, Proxy mode | Deterministic masking (embeddings, batch) isn't configured on this deployment. |
| document_pii_blocked | 403 | Gateway mode, Proxy mode | An attached document holds data your organization doesn't allow (`categories`). |
| document_unreadable | 403 | Gateway mode, Proxy mode | An attached document couldn't be read to scan it (encrypted or damaged). |
| edm_chunk_too_large | 413 | Gateway mode | An EDM upload chunk is over the limit. |
| edm_key_event_unavailable | 503 | Gateway mode | The EDM key couldn't be issued. |
| edm_unavailable | 503 | Gateway mode, Proxy mode | Your Exact Data Match datasets couldn't be loaded in time. |
| egress_port_denied | 403 | Proxy mode | The proxy only connects to allowed ports. |
| embeddings_body_unreadable | 422 | Gateway mode, Proxy mode | An embeddings or batch body isn't the JSON the provider documents. |
| file_analysis_pending | 503 | Gateway mode, Proxy mode | An attached file is still being analysed. |
| file_blocked | 403 | Gateway mode, Proxy mode | The Sandbox found an attached file unsafe under your organization's policy. |
| file_too_large | 413 | Gateway mode, Proxy mode | An attached file is over the Sandbox's size limit. |
| file_unreadable | 403 | Gateway mode, Proxy mode | An attached file couldn't be read to check it. |
| https_tunnel_required | 403 | Proxy mode | A plain-HTTP proxy request named an inspected host. Only CONNECT tunnels are authenticated and inspected. |
| idp_unavailable | 503 | Platform API | The identity provider couldn't be reached. |
| image_blocked | 403 | Gateway mode, Proxy mode, Browser DLP | Your organization doesn't allow images. |
| image_redaction_failed | 403 | Gateway mode, Proxy mode | Text in an image matched your rules and couldn't be covered. |
| image_unreadable | 403 | Gateway mode, Proxy mode | An image couldn't be read to scan its text. |
| invalid_api_key | 401 | Gateway mode, Proxy mode | The Maskflare API key is unknown, revoked or expired. |
| invalid_content_length | 400 | Proxy mode | The Content-Length header doesn't describe the body. |
| invalid_request | 400 | Gateway mode | A /v1/mask or /v1/unmask body didn't match the API. |
| invalid_subject_tenant | 400 | Gateway mode, Proxy mode | `X-MaskFlare-Subject-Tenant` was repeated or malformed. |
| invalid_token | 401 | Platform API | The access token is expired, malformed or from another issuer. |
| masking_module_disabled | 403 | Gateway mode, Proxy mode | Masking is turned off for your organization, and Maskflare never forwards AI traffic unmasked. |
| masking_rules_unavailable | 503 | Gateway mode, Proxy mode | The masking rules couldn't be loaded or applied. |
| masking_unavailable | 503 | Gateway mode, Proxy mode | Masking failed and your organization blocks rather than forward unmasked. |
| mcp_destination_not_allowed | 403 | Gateway mode | The MCP server resolves to a private or internal address. |
| mcp_server_unreachable | 502 | Gateway mode | The MCP server didn't answer. |
| method_not_allowed | 405 | Gateway mode | This route doesn't take that HTTP method. |
| misdirected_request | 421 | Proxy mode | A request inside a proxy tunnel named another host than the CONNECT. |
| missing_api_key | 401 | Gateway mode, Proxy mode | The request carried no Maskflare API key. (Proxy mode answers 407 with `Proxy-Authenticate`, so clients that wait for a challenge send it.) |
| missing_model | 400 | Gateway mode | A live (voice) session was opened without `?model=`. |
| missing_provider_key | 401 | Gateway mode, Proxy mode | The connection is pass-through and the request carried no provider key. |
| missing_token | 401 | Platform API | A platform API call had no access token. |
| model_not_allowed | 403 | Gateway mode, Proxy mode | The model isn't on the environment's allowed list. |
| module_disabled | 403 | Gateway mode, Proxy mode, Platform API | The feature this endpoint belongs to is turned off for your organization. |
| org_ambiguous | 400 | Platform API | You belong to several organizations and the request didn't say which one. |
| org_forbidden | 403 | Platform API | The organization in `X-Maskflare-Organization` isn't one of yours. |
| org_missing | 403 | Platform API | The token names no organization you belong to. |
| organization_inactive | 403 | Gateway mode, Proxy mode, Platform API | The organization the key belongs to is suspended. |
| platform_unavailable | 503 | Gateway mode, Proxy mode | Maskflare's control plane couldn't be reached. |
| provider_blocked | 403 | Gateway mode, Proxy mode | Your organization blocks this AI provider. |
| provider_key_unreadable | 403 | Gateway mode, Proxy mode | The provider key stored on the connection can't be decrypted. |
| provider_not_enabled | 403 | Gateway mode, Proxy mode | The environment has no enabled connection for this AI provider. |
| proxy_auth_required | 403 | Proxy mode | A connection to an inspected AI host reached the proxy without an authenticated tunnel. |
| proxy_state_invalid | 503 | Proxy mode | The proxy lost track of the tunnel. |
| rate_limited | 429 | Gateway mode, Proxy mode | The environment's requests-per-minute limit was reached. |
| ratelimit_unavailable | 503 | Gateway mode, Proxy mode | The rate limiter couldn't be reached, and Maskflare fails closed. |
| redaction_key_cannot_forward | 403 | Gateway mode, Proxy mode | A redaction key was used on a provider route. Redaction keys only call /v1/mask and /v1/unmask. |
| request_inspection_failed | 503 | Proxy mode | The proxy couldn't inspect the request, so it didn't forward it. |
| request_too_large | 413 | Gateway mode, Proxy mode | The request body is over the environment's size limit. |
| response_too_large | 502 | Gateway mode, Proxy mode | A response Maskflare must read whole (a block rule or re-hydration applies) is over 16 MiB. |
| role_forbidden | 403 | Platform API | Your role in the organization doesn't allow this action. |
| sensitive_data_blocked | 403 | Gateway mode, Proxy mode, Browser DLP | A block rule matched. `rule_keys` names the rules; no value is ever returned. |
| sensitive_data_volume | 403 | Gateway mode, Proxy mode, Browser DLP | The request went past a volume threshold (`thresholds`: what was counted, the limit and how many it carried). |
| service_forbidden | 403 | Platform API | The calling service isn't allowed on this internal endpoint. |
| tls_inspection_required | 403 | Proxy mode | The proxy can't guarantee it inspects this tunnel, so it refuses it. |
| token_input_unsupported | 422 | Gateway mode, Proxy mode | Embeddings input given as token ids can't be masked. |
| too_many_tokens | 400 | Gateway mode | /v1/unmask was asked for more than 100 items. |
| unknown_mcp_server | 404 | Gateway mode | No MCP server with that name is registered in the key's environment. |
| unknown_provider | 404 | Gateway mode | The gateway path names no provider Maskflare supports. |
| unsupported_charset | 415 | Gateway mode | The body's charset isn't UTF-8, UTF-16 or Latin-1. |
| unsupported_content_encoding | 415 | Gateway mode, Proxy mode | The body uses a coding Maskflare can't inspect. |
| unsupported_path_encoding | 400 | Gateway mode, Proxy mode | The provider path holds characters Maskflare refuses to guess about (percent-escapes, `;`, `@`, `+`, ...). |
| upstream_read_failed | 502 | Gateway mode | The provider's response broke off. |
| upstream_unavailable | 502 | Gateway mode | The live session couldn't be opened with the provider. |
| upstream_unreachable | 502 | Gateway mode | Maskflare couldn't connect to the AI provider. |
| voice_options_need_deterministic | 400 | Gateway mode | `spoken` or `spans` was sent without deterministic masking. |