Prismatic API/Docs/Errors and troubleshooting
Dashboard
Documentation

Errors and troubleshooting

Prismatic returns protocol-compatible error payloads so clients can handle authentication, billing, validation and model availability clearly.

Common errors

401invalid_api_keyThe API key is missing, invalid, or revoked.
403permission_deniedYou do not have permission to perform this request.
403ip_not_allowedThis request is not allowed from the current IP address.
403account_suspendedThis account is suspended. Contact support for assistance.
403model_not_allowedThis API key is not allowed to use the requested model.
404endpoint_not_foundThe requested API endpoint was not found.
405method_not_allowedThe HTTP method is not allowed for this endpoint.
400invalid_requestThe request is invalid. Check the request parameters and try again.
413request_too_largeThe request exceeds the maximum allowed size.
415unsupported_media_typeThe request content type is not supported by this endpoint.
400unsupported_featureThis endpoint does not support the requested feature.
404model_not_foundThe requested model was not found or is not available.
400model_capability_unavailableThe requested model does not support this capability.
400context_length_exceededThe request exceeds the model's context limit. Reduce the input or requested output budget and try again.
400output_limit_exceededThe requested output limit exceeds the model's maximum.
400content_policy_violationThe request or generated content was blocked by a safety policy.
429rate_limit_exceededRate limit exceeded. Please retry later.
402billing_requiredBilling is required to process this request.
402credit_balance_exhaustedThe PAYG credit balance is insufficient for this request.
429quota_exceededThe subscription quota for this request has been exhausted.
429spend_limit_exceededThe configured spending limit has been reached.
403model_not_in_planThe requested model is not included in the active plan.
503billing_unavailableBilling could not be verified temporarily. Please retry later.
409idempotency_conflictThis idempotency key was already used with a different request.
409request_in_progressA request with this idempotency key is still in progress.
409outcome_unknownThe request outcome is unknown. Do not retry automatically with a new idempotency key.
404resource_not_foundThe requested resource does not exist or is not accessible.
409resource_conflictThe resource state conflicts with this operation.
410resource_expiredThe requested resource has expired.
503resource_unavailableThe requested resource is temporarily unavailable. Please retry later.
502model_errorThe model returned an invalid or incomplete response.
503model_unavailableThe requested model is temporarily unavailable. Please retry later.
503service_unavailableThe service is temporarily unavailable. Please retry later.
504request_timeoutThe request timed out before completion.
500internal_errorAn internal error occurred. Contact support with the request ID.

Protocol error shapes

  • OpenAI-compatible endpoints return error.message, error.type, error.code, error.param and a top-level request_id.
  • Anthropic-compatible endpoints return the native type: error envelope with error.type, error.code, optional error.param and request_id.
  • Gemini-compatible endpoints return a Google error envelope. google.rpc.ErrorInfo.metadata.prismatic_code carries the Prismatic code and metadata.request_id carries the request ID.
  • SSE streams emit the same protocol-native code and request ID in at most one terminal error event. The HTTP status cannot change after a 200 stream has started.
  • Treat code as the stable contract. The English message may change and must not be parsed.

Error headers

  • x-request-id is generated by Prismatic as req_* for every proxy request; an incoming value with that name is ignored.
  • x-client-request-id may contain 1 to 128 safe characters and is echoed separately when valid.
  • x-prismatic-error-code repeats the canonical code when headers have not already been committed.
  • Retry-After is present only when Prismatic has a reliable retry delay. Error responses use Cache-Control: no-store.

Retry and compaction policy

  • Use context_length_exceeded as the signal to compact the conversation or reduce the input/output budget.
  • Retry rate_limit_exceeded after Retry-After when present. Retry temporary *_unavailable, request_timeout and billing_unavailable failures with bounded exponential backoff.
  • Do not retry validation, permission, billing-balance, quota, spend-limit or conflict errors until the underlying request or account state changes.
  • Never replay outcome_unknown automatically with a new idempotency key. Reconcile the original key or resource first.

Troubleshooting

401 on every request

Regenerate the key in the dashboard, confirm the prefix is correct and verify the integration did not trim the header.

Model not found

Call GET /v1/models with the same API key and use one of the returned public IDs.

Billing errors

Check active subscription quota first, then wallet balance and PAYG enabled state.

Streaming stops early

Ensure the client consumes the SSE stream to completion so final usage can be captured.

PreviousModelsNextBilling, quotas and PAYG