REST API

Errors, rate limits, and retries

Handle failures predictably without duplicate credit use or accidental retry storms.

Verified against the implementation · 2026-09-09

Error envelope

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_required",
    "message": "Idempotency-Key is required for AI operations.",
    "param": "Idempotency-Key",
    "requestId": "req_..."
  }
}

Client and authorization errors use invalid_request_error. Unexpected server failures use api_error. Always log error.code and requestId; do not build logic from the human-readable message.

Common errors

HTTP	Code	Action
400	invalid_request	Correct the field identified by param/details
400	idempotency_key_required	Add a stable unique key for the logical AI operation
401	authentication_required	Send a Bearer token
401	invalid_api_key	Replace an invalid, expired, or revoked REST key
401	oauth_required	Use OAuth instead of an API key for remote MCP
403	insufficient_scope	Authorize the required scope
403	email_verification_required	Verify the PrompTessor account email
403	public_platform_requires_paid_plan	Activate a paid plan
409	idempotency_conflict	Do not reuse a key with a different request body
429	rate_limit_exceeded	Wait for RateLimit-Reset or Retry-After
429	concurrency_limit_exceeded	Wait for active AI work to complete
429	usage_exhausted	Wait for renewal or add add-on credits
429	active_upload_limit_exceeded	Delete or consume an active upload
429	upload_storage_limit_exceeded	Release active upload storage or use a smaller file
409	webhook_endpoint_limit_reached	Delete an unused webhook endpoint or change plan

Plan-based platform limits

Plan tier	AI/min	Read/min	Concurrent AI	API keys	Webhooks	Active uploads
Free	0	0	0	0	0	0
Pro	30	120	3	3	3	10 / 50 MB
Pro+	60	240	6	5	5	25 / 250 MB
Max	120	480	12	10	10	50 / 1 GB

Pro Lifetime, Pro+ Lifetime, and Max Lifetime use their corresponding tier limits. The minute window is enforced for both the account and the individual credential; the higher observed count determines remaining capacity.

Safe retry strategy

1
Generate one idempotency key
Create it once per logical AI operation and persist it alongside your job.
2
Retry transient failures
Retry network errors, 429, and 5xx with exponential backoff and jitter. Honor Retry-After when present.
3
Reuse the same key and body
A completed response can be replayed for up to 24 hours and includes Idempotent-Replayed: true.
4
Stop on validation and authorization errors
Do not retry 400, 401, 403, or idempotency_conflict until the request or credentials change.