Error Reference

This is the single canonical catalog of error codes returned by the Prezent Platform API. Every documented endpoint (except SCIM, which follows RFC 7644 and is documented separately) reports failures using the same uniform error envelope and draws error.code from the stable catalog below.

For rate-limit specifics and the two distinct 429 surfaces, see the Developer Guide → Rate limits. For the full interactive endpoint reference, see the API Reference.

The error envelope

On failure, every endpoint returns the uniform error envelope:

{
  "success": false,
  "data": null,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Company rate limit exceeded. Please try again later.",
    "details": { "category": "autogenerator" }
  }
}

Field	Type	Description
success	boolean	Always false on error.
data	null	Always null on error.
error.code	string	A stable identifier from the catalog below.
error.message	string	A human-readable description (English).
error.details	object	Optional structured details (validation failures, downstream-service info, retry hints, etc.). May be absent.

error.code is a stable string: a code never changes its meaning or its HTTP status once published. Branch your error handling on error.code (and on the HTTP status), not on error.message — message text may be refined over time. Handlers may emit additional legacy keys alongside success, data, and error; these are not part of the contract and may change without notice.

Error codes by HTTP status

400 Bad Request

Code	Meaning
BAD_REQUEST	Generic bad request.
INVALID_JSON	Request body is not valid JSON.
MISSING_REQUIRED_FIELD	A required field is absent from the request.
MISSING_QUERY_PARAM	A required query parameter is absent.
MISSING_CALLBACK_ID	callback_id was not provided.
MISSING_SLIDES_ARRAY	The slides array is missing or invalid.
MISSING_PROMPT	The prompt field is missing.
MISSING_TEMPLATE_ID	The template_id field is missing.
MISSING_FILE_CONTENT	File content or file name is missing.
MISSING_SHARE_DETAILS	shareDetails is required when type is feedback.
INVALID_TYPE	An invalid type value was provided.
INVALID_DATA_TYPE	A field value has the wrong type.
INVALID_PAYLOAD	The payload format is invalid.
INVALID_REQUEST	Generic invalid request.
API_REQUEST_FAILED	A downstream/external API request failed.
FILE_UPLOAD_FAILED	File upload failed.
INVALID_URL_SCHEME	Webhook target URL must use the https:// scheme.
INVALID_URL_PRIVATE_HOST	Webhook target URL must not resolve to a private, loopback, link-local, or metadata-service address.
INVALID_URL_PORT	Webhook target URL uses a disallowed port.
INVALID_EVENT_TYPE	One or more webhook event types are not in the published catalog. Use "*" for all events or a known type name.
INVALID_STREAM_REQUEST	The stream session request was rejected.

401 Unauthorized

Code	Meaning
INVALID_API_KEY	API key not found or not authorized.
EXPIRED_API_KEY	API key has expired. Generate a new key.
UNAUTHORIZED	Unauthorized access.

403 Forbidden

Code	Meaning
FORBIDDEN	Access to the resource is forbidden.
STREAM_CALLBACK_FORBIDDEN	The callback_id is owned by a different API key.

404 Not Found

Code	Meaning
ENDPOINT_NOT_FOUND	The requested endpoint does not exist or the key is not scoped to it.
RESOURCE_NOT_FOUND	The requested resource does not exist.
NOT_FOUND	Generic not-found.
WEBHOOK_SUBSCRIPTION_NOT_FOUND	The webhook subscription does not exist or is not owned by the calling API key.
STREAM_CALLBACK_NOT_FOUND	No job with that callback_id was found, or it is not owned by the calling API key.

405 Method Not Allowed

Code	Meaning
METHOD_NOT_ALLOWED	HTTP method not allowed for this endpoint.

409 Conflict

Code	Meaning
IDEMPOTENCY_KEY_REUSED_WITH_DIFFERENT_BODY	This Idempotency-Key was already used with a different request body. Reuse a key only for identical retried requests. See Idempotency.

415 Unsupported Media Type

Code	Meaning
UNSUPPORTED_FILE_TYPE	File extension or MIME type not accepted.

422 Unprocessable Entity

Code	Meaning
INVALID_INPUT	Input failed validation.
UNPROCESSABLE_ENTITY	Request is well-formed but semantically invalid.

429 Too Many Requests

Code	Meaning
TOO_MANY_REQUESTS	Gateway throttle exceeded (10 req/s, 5 burst, 1,000/day per key).
RATE_LIMIT_EXCEEDED	Per-company per-category rate limit hit.
USAGE_LIMIT_EXCEEDED	Plan-level usage cap reached. Contact your CSM to upgrade.
THROTTLED	Image search / replace throttle — slow down and retry.
MAX_RETRIES_EXCEEDED	Retry limit exhausted.

When you receive a 429, honour the Retry-After response header and use jittered exponential backoff. See Developer Guide → Rate limits for the header set emitted by each 429 surface.

5xx Server Errors

Code	HTTP	Meaning
INTERNAL_SERVER_ERROR	500	Unexpected server error.
EXTERNAL_SERVICE_ERROR	502	A downstream service returned an error.
SERVICE_UNAVAILABLE	503	Service temporarily unavailable.
GATEWAY_TIMEOUT	504	Upstream timeout.

Handling errors

A robust integration:

• Branches on error.code and the HTTP status, never on message text.
• Retries only idempotent or safely-retryable failures (for example 429, 503, 504) with jittered exponential backoff; pair retries with an Idempotency-Key so a retried write is never processed twice (see Idempotency).
• Treats 4xx validation errors as terminal — fix the request rather than retrying it.
• Logs error.details when present; it carries the structured context (which field failed, which category was throttled, retry hints) needed to diagnose the failure.

Where to go next

If you want to	Go to
Understand rate limits and quotas	Developer Guide → Rate limits
Retry safely after a network error	Developer Guide → Idempotency
Browse every endpoint interactively	API Reference
Verify webhook deliveries	Webhooks