Error Handling

Branch on error.code. It is the machine-readable identifier and it is stable; message is for humans and can change. Every code on this page is checked against the codes the API actually emits, so a code you find here is one you can receive.

The error envelope

Every error is a JSON object with a single error key:

{
  "error": {
    "message": "PromptGuard API key required. Please provide via X-API-Key header.",
    "type": "authentication_error",
    "code": "missing_api_key"
  }
}

Field	Always present	Meaning
`message`	Yes	Human-readable, safe to log and show a developer
`code`	Yes	What to branch on
`type`	Almost always	A broad category. The generic `HTTP_ERROR` and `INTERNAL_SERVER_ERROR` envelopes omit it

Some codes add fields of their own, at the top level of error — there is no nested details object. retry_after, for example, is error.retry_after. The fields each code adds are shown in its section below. One exception: a request body that fails schema validation on an endpoint with a typed body (for example POST /api/v1/guard without messages) is rejected with HTTP 422 and FastAPI’s {"detail": [...]} body, which has no error key. Treat any 422 as a bug in the request, not something to retry. To correlate a failure with our logs, quote the X-Request-ID response header. Security decisions also carry X-PromptGuard-Event-ID.

Error code reference

Code	Status	Retry?	Meaning
`missing_api_key`	401	No	No PromptGuard API key was sent
`invalid_api_key`	401	No	The key is malformed or unknown — or, on the proxy, the upstream provider rejected your provider key
`disabled_api_key`	401	No	The key exists but has been disabled
`expired_api_key`	401	No	The key has passed its expiry (set at creation, or the grace window of a rotation)
`scope_denied`	403	No	The key’s scopes do not permit this endpoint
`ip_not_allowed`	403	No	The caller’s IP is not on the organization’s IP allowlist
`ip_allowlist_error`	403	Yes, with backoff	The IP allowlist could not be checked, so the request was refused
`ip_reputation_blocked`	403	No	The caller’s IP is on a network threat list (self-hosted deployments that enable it)
`access_list_block`	403	No	An access-list rule on the project refused the caller
`request_blocked`	403	No	The input scan blocked the request
`response_blocked`	200	No	The output scan blocked the completion (see Blocked responses)
`content_blocked`	SSE event	No	The output scan blocked a streamed completion
`invalid_header`	400	No	A header contains non-ASCII characters — usually a pasted API key with a look-alike letter
`prompt_too_large`	413	No	The prompt exceeds the maximum size
`token_limit_exceeded`	413	No	The prompt exceeds the project’s per-request token limit
`request_body_too_large`	413	No	The Guard API request body exceeds the size limit
`rate_limit_exceeded`	429	Yes, after `retry_after`	A per-minute request limit was hit (PromptGuard’s own, or the provider’s on the proxy)
`bot_detected`	429	Not automatically	The traffic pattern was classified as automated abuse; `retry_after` is included
`monthly_quota_exceeded`	429	Not in a loop	The plan’s monthly request quota is spent
`spending_limit_exceeded`	429	Not in a loop	The account’s monthly spending cap is reached
`subscription_inactive`	429	Never	The subscription is cancelled, past due, unpaid or paused, or no plan covers the key’s organization
`detection_unavailable`	503	Yes, with backoff	The project fails closed and the security scan could not run
`model_not_found`	404	No	The upstream provider does not know the model
`provider_error`	Provider’s status	5xx only	The upstream provider returned an error
`HTTP_ERROR`	4xx	No	A generic request error, such as a body that is not valid JSON
`INTERNAL_SERVER_ERROR`	500	Yes, with backoff	An unexpected failure on our side; quote `error_id` to support

Every 429 code shares one status. A client that retries every 429 will retry subscription_inactive forever, and will hammer a spent quota until the next billing month. Branch on code before you back off.

Authentication and authorization

Missing or invalid key (401)

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

missing_api_key, disabled_api_key and expired_api_key have the same shape. None is fixed by retrying: check that PROMPTGUARD_API_KEY is set, that the key starts with pg_live_, and that it is still enabled and unexpired in the dashboard. After a key rotation, expired_api_key means the old key’s grace window has closed. On the proxy, an invalid_api_key whose message names a provider (for example “Incorrect Anthropic API key provided”) means the provider rejected the provider key configured on your project, not your PromptGuard key.

Scope denied (403)

A key created with restricted scopes, or a scan-only device credential, is refused on endpoints outside those scopes:

{
  "error": {
    "message": "This API key's scopes do not permit this endpoint. Create a key with the required scope or use an unrestricted key.",
    "type": "insufficient_scope",
    "code": "scope_denied"
  }
}

The response does not say which scope was missing. Create a key with the scope the endpoint needs, or use an unrestricted key.

Rate limits and quotas

Rate limit exceeded (429)

{
  "error": {
    "message": "Rate limit exceeded. Please retry later.",
    "type": "rate_limit_exceeded",
    "code": "rate_limit_exceeded",
    "retry_after": 42
  }
}

retry_after is in seconds and matches the Retry-After header. When the provider rate-limits a proxied request, the code is the same but type is rate_limit_error, there is no retry_after in the body, and the provider’s own Retry-After header is passed through — so read the header first.

Monthly quota exceeded (429)

{
  "error": {
    "message": "Monthly quota of 100,000 requests exceeded. Upgrade to Scale for 500,000 requests/month. Or enable pay-as-you-go in your dashboard to keep going without upgrading.",
    "type": "quota_exceeded",
    "code": "monthly_quota_exceeded",
    "current_plan": "pro",
    "requests_used": 100000,
    "requests_limit": 100000,
    "upgrade_url": "https://app.promptguard.co/dashboard/billing",
    "on_demand_url": "https://app.promptguard.co/dashboard/spending",
    "retry_after": 1209600
  }
}

Here retry_after is the number of seconds until the quota resets at the start of the next month — often days. Surface upgrade_url or on_demand_url instead of sleeping. on_demand_url is present only on plans that sell pay-as-you-go; on Free it is absent and the message names only the upgrade.

Spending limit exceeded (429)

{
  "error": {
    "message": "Monthly spending limit of $500.00 exceeded. Current spending: $500.12. Please increase your spending limit or wait until next billing cycle.",
    "type": "spending_limit_exceeded",
    "code": "spending_limit_exceeded",
    "current_plan": "scale",
    "current_spending": 500.12,
    "spending_limit": 500.0,
    "settings_url": "https://app.promptguard.co/dashboard/spending",
    "retry_after": 1209600
  }
}

Subscription inactive (429)

{
  "error": {
    "message": "Your pro subscription is not active (status: past_due). Update your payment method to settle the outstanding invoice.",
    "type": "subscription_inactive",
    "code": "subscription_inactive",
    "current_plan": "pro",
    "subscription_status": "past_due",
    "reactivate_url": "https://app.promptguard.co/dashboard/billing"
  }
}

There is deliberately no retry_after: waiting does not fix this. Nothing changes until the subscription is reactivated at reactivate_url. subscription_status is none when no plan covers the key’s organization at all: a provider answered for its bill and no longer does, and the organization has no owner of its own. Nothing at reactivate_url changes that one. Contact support.

Retrying correctly

const RETRYABLE_CODES = new Set([
  'rate_limit_exceeded',
  'detection_unavailable',
  'INTERNAL_SERVER_ERROR',
]);

function retryDelayMs(response, body, attempt) {
  // Prefer the header: it is present on PromptGuard's own 429s and passed
  // through from the provider on proxied ones.
  const header = Number(response.headers.get('retry-after'));
  if (header > 0) return header * 1000;
  if (body.error.retry_after > 0) return body.error.retry_after * 1000;
  return Math.min(1000 * 2 ** attempt, 30000) + Math.random() * 1000;
}

async function callWithRetry(request, maxRetries = 3) {
  for (let attempt = 0; ; attempt++) {
    const response = await request();
    if (response.ok) return response;

    const body = await response.json();
    const code = body.error?.code;

    const retryable =
      RETRYABLE_CODES.has(code) ||
      (code === 'provider_error' && response.status >= 500);

    if (!retryable || attempt >= maxRetries) {
      throw Object.assign(new Error(body.error.message), {
        status: response.status,
        code,
        error: body.error,
      });
    }
    await new Promise((r) => setTimeout(r, retryDelayMs(response, body, attempt)));
  }
}

monthly_quota_exceeded, spending_limit_exceeded and subscription_inactive are left out on purpose: each needs a person, not a retry. So is bot_detected: it carries retry_after, but an automatic retry loop is the behaviour that was flagged, so surface it instead.

Security blocks

Request blocked (403)

When the input scan blocks a proxied request, PromptGuard returns HTTP 403:

{
  "error": {
    "message": "Request blocked by security policy.",
    "type": "policy_violation",
    "code": "request_blocked",
    "event_id": "ac0ed289-1921-4d56-880b-063585836aea",
    "dashboard_url": "https://app.promptguard.co/dashboard/projects/{project_id}/interactions?event_id=ac0ed289-1921-4d56-880b-063585836aea"
  }
}

dashboard_url is present when the dashboard URL is configured. The threat category is not in the body; read the X-PromptGuard-Threat-Type and X-PromptGuard-Confidence response headers, and open the event in the dashboard under Projects → Interactions for the full audit record. The Guard API (POST /api/v1/guard) does not use this envelope: a blocked decision there is a normal 200 response with decision: "block".

Blocked responses

When the output scan blocks a non-streamed completion, the body carries code: "response_blocked" with the same fields as request_blocked:

{
  "error": {
    "message": "Response blocked by security policy.",
    "type": "policy_violation",
    "code": "response_blocked",
    "event_id": "ac0ed289-1921-4d56-880b-063585836aea"
  }
}

This body is currently delivered with HTTP 200, not 403. A client that only inspects the status code will treat it as a completion with no choices. Check for error in every successful proxy body.

Blocked streamed responses

With "stream": true, the output scan runs on the full accumulated body before any byte is emitted. There is no status code left to change by then, so a block is delivered as a terminating SSE error event — and it carries type: "content_filter" with code: "content_blocked":

{
  "error": {
    "message": "Response blocked by security policy.",
    "type": "content_filter",
    "code": "content_blocked",
    "event_id": "ac0ed289-1921-4d56-880b-063585836aea",
    "dashboard_url": "https://app.promptguard.co/dashboard/projects/{project_id}/interactions?event_id=ac0ed289-1921-4d56-880b-063585836aea"
  }
}

No part of the completion is written when this happens, so the event is the whole response. Branch on all three block codes:

const BLOCK_CODES = new Set([
  'request_blocked',    // input scan, 403
  'response_blocked',   // output scan, non-streaming
  'content_blocked',    // output scan, streaming
]);

const isBlocked = (body) => BLOCK_CODES.has(body?.error?.code);

Show the end user a neutral message and log event_id. Do not try to “clean” a blocked prompt with your own regexes and resend it: a rewrite that slips past the scan is exactly the evasion the scan exists to catch.

Detection unavailable (503)

A project configured to fail closed refuses to forward a request the scan could not evaluate:

{
  "error": {
    "message": "Security evaluation failed and this project is configured to fail closed, so the request was not forwarded. Retry shortly.",
    "type": "detection_unavailable",
    "code": "detection_unavailable",
    "detail": "TimeoutError"
  }
}

This is our outage, not a verdict on your content. Retry with backoff.

Provider errors

On the proxy, an error from the upstream provider is passed through with the provider’s status code and PromptGuard’s envelope:

{
  "error": {
    "message": "anthropic API is currently experiencing issues. Please try again later.",
    "type": "server_error",
    "code": "provider_error",
    "param": null
  },
  "status": 503
}

Provider status	`code`	`type`
401	`invalid_api_key`	`authentication_error`
404	`model_not_found`	`invalid_request_error`
429	`rate_limit_exceeded`	`rate_limit_error`
5xx	`provider_error`	`server_error`
Other 4xx	`provider_error`	`invalid_request_error`

Retry only the 5xx provider_error. The provider’s request id and rate-limit headers are passed through, so quote the provider’s request id to their support.

Unexpected errors (500)

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An unexpected error occurred",
    "error_id": "3f0b8c1e-6a0e-4d52-9a57-0c2a9a7f5b11"
  }
}

error_id equals the X-Request-ID header. Quote it to support.

Network errors

Connection failures never reach PromptGuard, so they carry no envelope. With fetch in Node.js the socket error is on err.cause:

const SOCKET_ERRORS = ['ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND'];

function isNetworkError(err) {
  return SOCKET_ERRORS.includes(err.cause?.code);
}

Retry these with exponential backoff, the same as a 5xx.

Testing your error handling

Build fixtures from the real envelopes above rather than inventing codes, so a test cannot pass against a code the API never sends:

function promptGuardError(status, error, headers = {}) {
  return new Response(JSON.stringify({ error }), {
    status,
    headers: { 'content-type': 'application/json', ...headers },
  });
}

test('retries a rate limit after Retry-After', async () => {
  const request = jest.fn()
    .mockResolvedValueOnce(promptGuardError(429, {
      message: 'Rate limit exceeded. Please retry later.',
      type: 'rate_limit_exceeded',
      code: 'rate_limit_exceeded',
      retry_after: 1,
    }, { 'retry-after': '1' }))
    .mockResolvedValueOnce(new Response('{}', { status: 200 }));

  await callWithRetry(request);
  expect(request).toHaveBeenCalledTimes(2);
});

test('does not retry an inactive subscription', async () => {
  const request = jest.fn().mockResolvedValue(promptGuardError(429, {
    message: 'Your pro subscription is not active (status: cancelled).',
    type: 'subscription_inactive',
    code: 'subscription_inactive',
  }));

  await expect(callWithRetry(request)).rejects.toMatchObject({ code: 'subscription_inactive' });
  expect(request).toHaveBeenCalledTimes(1);
});

Next Steps

Best Practices

Production deployment and reliability best practices

Rate Limits

Understanding and managing API rate limits

Troubleshooting

Common issues and debugging techniques

Monitoring

Set up comprehensive monitoring and alerts

Last reviewed 2026-09-16.

Get Started

Core Concepts

Gateway

Shadow AI

Guides

Cookbooks

Platform

Going to Production

Resources

Roadmap / Preview

The error envelope

Error code reference

Authentication and authorization

Missing or invalid key (401)

Scope denied (403)

Rate limits and quotas

Rate limit exceeded (429)

Monthly quota exceeded (429)

Spending limit exceeded (429)

Subscription inactive (429)

Retrying correctly

Security blocks

Request blocked (403)

Blocked responses

Blocked streamed responses

Detection unavailable (503)

Provider errors

Unexpected errors (500)

Network errors

Testing your error handling

Next Steps

Best Practices

Rate Limits

Troubleshooting

Monitoring

​The error envelope

​Error code reference

​Authentication and authorization

​Missing or invalid key (401)

​Scope denied (403)

​Rate limits and quotas

​Rate limit exceeded (429)

​Monthly quota exceeded (429)

​Spending limit exceeded (429)

​Subscription inactive (429)

​Retrying correctly

​Security blocks

​Request blocked (403)

​Blocked responses

​Blocked streamed responses

​Detection unavailable (503)

​Provider errors

​Unexpected errors (500)

​Network errors

​Testing your error handling

​Next Steps

Best Practices

Rate Limits

Troubleshooting

Monitoring

The error envelope

Error code reference

Authentication and authorization

Missing or invalid key (401)

Scope denied (403)

Rate limits and quotas

Rate limit exceeded (429)

Monthly quota exceeded (429)

Spending limit exceeded (429)

Subscription inactive (429)

Retrying correctly

Security blocks

Request blocked (403)

Blocked responses

Blocked streamed responses

Detection unavailable (503)

Provider errors

Unexpected errors (500)

Network errors

Testing your error handling

Next Steps