Reference
Errors
Every error response uses a consistent shape. Use the code field for programmatic handling — error messages are human-readable and may change over time.
#Error shape
Error response
{
"error": {
"code": "quota_exceeded",
"message": "Daily augmenter quota of 6 has been reached.",
"type": "tier_limit",
"requestId": "req_xxx",
"retryAfterMs": 3_600_000,
"docsUrl": "https://promptfloe.com/sdk/reference/errors#quota_exceeded"
}
}#Error codes
| Field | Type | Description |
|---|---|---|
| invalid_request | 400 | Request body fails validation. Inspect message for the offending field. |
| invalid_key | 401 | API key is malformed or missing. |
| expired_key | 401 | Key was rotated and the grace period ended. |
| missing_scope | 403 | Key is valid but lacks a scope required for this endpoint. |
| quota_exceeded | 403 | Workspace hit a daily limit. Wait for reset or upgrade tier. |
| tier_required | 403 | Endpoint requires a higher tier (e.g. augmenters need Basic+). |
| not_found | 404 | The resource doesn't exist or you don't have access. |
| conflict | 409 | Resource state conflict — alias already exists, lock contention. |
| unprocessable | 422 | Request is well-formed but semantically invalid (e.g. invalid template name). |
| rate_limited | 429 | Too many API calls. Back off using Retry-After. |
| internal_error | 500 | Server-side error. Safe to retry with backoff. |
| upstream_error | 502 | LLM provider returned an error. Auto-retried twice; if you see this, retry. |
| unavailable | 503 | Service temporarily unavailable. Retry with exponential backoff. |
| gateway_timeout | 504 | Upstream timed out. Safe to retry; LLM jobs may still be running server-side. |
#Retry guidance
| Field | Type | Description |
|---|---|---|
| 4xx (except 429) | don't retry | Client-side errors — fix the request and try again. |
| 429 | back off | Honor Retry-After header. Default to exponential backoff if missing. |
| 5xx | retry | Use exponential backoff (1s, 2s, 4s, 8s with jitter). The SDK does this for you up to maxRetries. |
The SDK auto-retries 429 + 5xx by default. Disable per-call with maxRetries: 0 for idempotency-sensitive operations.
#Request IDs
Every response — success or failure — includes an X-Request-Id header. Quote it when contacting support or filing bugs.
#Where to go next
PromptFloe developer docs