Use this guide to handle failed API responses consistently. Every /v1/*
error follows the same envelope, and every doc_url in that envelope
links into the reference table on this page.
Error envelope
{
"error": {
"type": "invalid_request_error",
"code": "missing_fields",
"message": "template_id and scene_revision are required.",
"doc_url": "https://stackfill.com/docs/errors/missing_fields",
"request_id": "req_123"
}
}
Fields:
type — high-level family: authentication_error, permission_error,
invalid_request_error, not_found_error, plan_limit_error,
rate_limit_error, api_error, service_unavailable.
code — stable machine-readable identifier. Stable across API
versions; safe to switch on.
message — human-readable summary. May change wording without notice.
doc_url — deep-links to the matching row in the reference
on this page.
request_id — repeat back to support to look up the offending request.
Common status codes
| Status |
Meaning |
| 400 |
Invalid JSON, missing fields, or invalid parameters. |
| 401 |
Missing or invalid API key. |
| 402 |
Plan or entitlement limit. |
| 403 |
Origin, scope, or permission failure. |
| 404 |
Resource not found for this team. |
| 409 |
Conflict, usually duplicate mapping or wrong state. |
| 410 |
Gone — session/demo/fill has expired. |
| 413 |
Upload exceeds the per-asset size cap. |
| 415 |
Unsupported media type. |
| 422 |
Validation or idempotency mismatch. |
| 429 |
Rate limit exceeded. |
| 500 |
Unexpected API error. Safe to retry once after a short delay. |
| 502 |
Renderer container unreachable or failed. |
| 503 |
Subsystem (D1/KV/R2/Stripe/webhook secrets) not configured. |
Common handling
- Show user-recoverable copy for 400, 402, 403, 404, 409, 410, 413, 415, 422.
- Retry only 429 and transient 5xx, and respect
Retry-After when present.
- Treat 5xx as transient unless the same
code repeats — *_not_configured
503s mean an operator needs to set a secret.
request_id is your friend. Log it on every failed call.
Looking up a specific code
doc_url URLs follow the shape https://stackfill.com/docs/errors/<code>.
The platform redirects those to this page with the code as the URL
fragment, so the row scrolls into view automatically. You can also use
the in-page search (Cmd/Ctrl + F) to find a code.
Reference
Authentication (401)
| Code |
Type |
What it means |
authentication_required |
authentication_error |
No Authorization: Bearer <key> header. Send your API key. |
invalid_api_key |
authentication_error |
Header present but malformed, unknown, or revoked. |
api_key_expired |
authentication_error |
Key passed its expires_at. Rotate or create a new one. |
api_key_rotated |
authentication_error |
Key was rotated more than 24 hours ago. Swap to the new key in Link: rel="successor-version". |
invalid_publishable_key |
authentication_error |
Public widget routes only accept publishable (pk_) keys. |
invalid_embed_session_secret |
authentication_error |
client_secret from the URL fragment doesn't match the session row. |
embed_session_secret_required |
authentication_error |
Embed runtime called without a client_secret. |
invalid_access_token |
authentication_error |
One-time hosted-fill access token is malformed or revoked. |
session_required |
authentication_error |
sf_session cookie missing or expired on a /app or /admin route. |
demo_expired |
authentication_error |
24-hour demo workspace has expired. Sign up for a real plan. |
sweep_unauthorized |
authentication_error |
/api/admin/webhooks/sweep needs platform admin or the WEBHOOK_SWEEP_SECRET bearer. |
Permission / scope / origin (403)
| Code |
Type |
What it means |
insufficient_scope |
authentication_error |
Key authenticated but lacks the scope this endpoint requires. |
origin_not_allowed |
authentication_error |
Browser request from an Origin not in the publishable key's allowlist. |
ip_not_allowed |
authentication_error |
Secret key's IP allowlist blocked this caller. |
publishable_key_required |
authentication_error |
Endpoint is browser-only — use a publishable (pk_) key. |
secret_key_required |
authentication_error |
Endpoint is server-only — use a secret (sk_) key, not publishable. |
access_token_mismatch |
permission_error |
Hosted-fill token doesn't authorize the requested fill. |
platform_admin_required |
permission_error |
/admin + /api/admin/* are restricted to PLATFORM_ADMINS. |
Plan / billing (402)
| Code |
Type |
What it means |
api_plan_required |
plan_limit_error |
Public API needs Pro+. Upgrade in the dashboard. |
embed_plan_required |
plan_limit_error |
Storefront embed needs Pro+. Upgrade in the dashboard. |
template_limit_reached |
plan_limit_error |
Plan's template cap is full. Archive one or upgrade. |
render_limit_reached |
plan_limit_error |
The month's final renders are used up. Buy a render pack (500 more final renders, $39, one-time) or upgrade in Settings → Plan and billing; the allowance resets with the billing period. On the hosted fill page and in the widget the message is written for the shop's customer ("This shop has used up its monthly allowance… contact the sender") and the shop's billing address gets one alert a day. |
feature_not_included |
plan_limit_error |
The plan lacks this feature (for example hosted fill links on Free, or anything on an expired demo). Hosted fill pages show the customer "This fill link isn't active right now. Please contact the sender." |
subscription_inactive |
plan_limit_error |
Subscription past due. Update payment in the customer portal. |
subscription_canceled |
plan_limit_error |
Subscription was canceled; period_end has passed. Resubscribe. |
Not found (404)
These all mean "no record matches that ID for the calling team".
404 instead of 403 to avoid leaking existence to unrelated tenants.
| Code |
Type |
What it means |
not_found |
not_found_error |
Generic — path not handled by the API. |
wrong_host |
not_found_error |
/v1/* is served at api.stackfill.com. The apex returns this hint. |
template_not_found |
not_found_error |
Template ID missing or archived. |
template_not_live |
not_found_error |
Template exists but isn't published to live. Call POST /v1/templates/:id/publish. |
template_removed |
not_found_error |
The hosted fill link's template was deleted (archived) by the shop. The link stays retired; publish a new template for a fresh link. |
fill_not_found |
not_found_error |
Fill ID missing or expired. |
render_not_found |
not_found_error |
Render ID missing for this team. |
render_blob_missing |
not_found_error |
Render row exists but the R2 blob is gone (rare, contact support). |
embed_application_not_found |
not_found_error |
Publishable key isn't linked to any embed app. |
embed_session_not_found |
not_found_error |
Session ID missing or expired. |
product_mapping_not_found |
not_found_error |
No mapping for this SKU/product_id. |
webhook_endpoint_not_found |
not_found_error |
Endpoint ID missing or owned by another team. |
webhook_delivery_not_found |
not_found_error |
Delivery row missing under that endpoint. |
api_key_not_found |
not_found_error |
API key ID missing or revoked. |
publishable_key_not_found |
not_found_error |
Publishable key not in the catalog. |
font_not_found |
not_found_error |
Font asset missing for this team. |
font_blob_missing |
not_found_error |
Font row exists but the R2 blob is gone. |
image_asset_not_found |
not_found_error |
Image asset missing. |
image_file_not_found |
not_found_error |
Image row exists but the R2 blob is gone. |
scene_not_found |
not_found_error |
Template has no scene rows; ingest may have failed. |
selection_set_not_found |
not_found_error |
Selection set ID missing. |
brand_logo_not_found |
not_found_error |
Brand logo asset missing. |
company_not_found |
not_found_error |
Company (CRM) ID missing. |
client_user_not_found |
not_found_error |
Client (CRM) user missing. |
project_not_found |
not_found_error |
Project ID missing. |
team_not_found |
not_found_error |
Team ID missing. |
user_not_found |
not_found_error |
User ID missing. |
plan_not_found |
not_found_error |
Plan ID missing in the catalog. |
billing_team_not_found |
not_found_error |
Stripe customer references a team we no longer have. |
setting_not_found |
not_found_error |
Operator setting key not found. |
access_token_expired |
not_found_error |
Hosted-fill one-time token already used or expired. |
Bad request (400)
Almost always "you sent JSON we can't accept". The message field
spells out which field. Read it once during integration, then drop the
verbose check.
| Code |
Type |
What it means |
invalid_json |
invalid_request_error |
Request body didn't parse as JSON. |
invalid_multipart |
invalid_request_error |
Multipart upload couldn't be parsed. |
missing_fields |
invalid_request_error |
Required JSON fields missing. |
missing_required_field |
invalid_request_error |
A single named field is missing. |
missing_asset_fields |
invalid_request_error |
Asset upload missing kind/scope/file. |
missing_asset_name |
invalid_request_error |
Asset name field missing. |
missing_allowed_origins |
invalid_request_error |
Publishable key needs at least one allowed origin. |
invalid_mode |
invalid_request_error |
mode must be live or test. |
invalid_kind |
invalid_request_error |
Asset kind outside the allowed enum. |
invalid_scene |
invalid_request_error |
Scene JSON failed validation. |
invalid_plan |
invalid_request_error |
Plan ID not in the catalog or not active. |
invalid_billing_interval |
invalid_request_error |
interval must be monthly or annual. |
invalid_pricing_mode |
invalid_request_error |
Pricing mode unrecognized. |
invalid_features_json |
invalid_request_error |
Plan feature JSON failed validation. |
invalid_limits_source |
invalid_request_error |
Limits-source field unrecognized. |
invalid_setting_key |
invalid_request_error |
Operator setting key outside the allowlist. |
invalid_setting_value |
invalid_request_error |
Operator setting value rejected by validator. |
invalid_setting_scope |
invalid_request_error |
Operator setting scope rejected. |
invalid_application_status |
invalid_request_error |
Embed app status outside active/paused/archived. |
invalid_asset_scope |
invalid_request_error |
Asset scope not team or template. |
invalid_client_email |
invalid_request_error |
Client email field failed RFC 5322 validation. |
invalid_client_user_status |
invalid_request_error |
Client-user status outside the allowlist. |
invalid_company_status |
invalid_request_error |
Company status outside the allowlist. |
invalid_key_mode |
invalid_request_error |
API key mode must be live or test. |
invalid_key_status |
invalid_request_error |
API key status outside active/revoked. |
invalid_key_type |
invalid_request_error |
API key type outside secret/publishable. |
invalid_last_team |
invalid_request_error |
Cannot remove yourself from your only team. |
invalid_mapping_status |
invalid_request_error |
Product mapping status outside the allowlist. |
invalid_project_status |
invalid_request_error |
Project status outside the allowlist. |
invalid_session_status |
invalid_request_error |
Embed session status outside the allowlist. |
invalid_template_status |
invalid_request_error |
Template status outside the allowlist. |
invalid_webhook_status |
invalid_request_error |
Webhook endpoint status outside active/paused/disabled. |
invalid_webhook_url |
invalid_request_error |
Webhook URL must be https and absolute. |
invalid_stripe_event |
invalid_request_error |
Stripe payload failed signature or shape check. |
invalid_accent_color |
invalid_request_error |
Color value not a valid hex. |
invalid_primary_color |
invalid_request_error |
Color value not a valid hex. |
cannot_delete_self |
invalid_request_error |
Admins can't delete their own user from /admin. |
Conflicts (409)
You're trying to write a row that conflicts with state or another row.
| Code |
Type |
What it means |
client_email_taken |
invalid_request_error |
Another client (CRM) record uses that email. |
company_name_taken |
invalid_request_error |
Another company (CRM) uses that display name. |
team_email_taken |
invalid_request_error |
Another team uses that contact email. |
user_email_taken |
invalid_request_error |
Another user uses that email. |
project_name_taken |
invalid_request_error |
Project name collides within the team. |
plan_exists |
invalid_request_error |
Plan ID already in the catalog. |
product_mapping_exists |
invalid_request_error |
Mapping for that external_product_id already exists. |
setting_exists |
invalid_request_error |
Operator setting already present. |
template_archived |
invalid_request_error |
Cannot mutate an archived template. |
no_scene |
invalid_request_error |
Template has no scene; publish it after ingest finishes. |
render_not_ready |
invalid_request_error |
Render is still pending; wait for succeeded. |
delivery_already_succeeded |
invalid_request_error |
Webhook delivery already succeeded — no retry needed. |
endpoint_disabled |
invalid_request_error |
Webhook endpoint disabled after 20 consecutive failures. Re-enable in the dashboard. |
fill_expired |
invalid_request_error |
Fill's expires_at has passed. |
fill_not_open |
invalid_request_error |
Fill is finalized or archived; reopen by creating a new one. |
key_already_rotated |
invalid_request_error |
API key is already mid-rotation; wait for the grace window to end. |
key_not_active |
invalid_request_error |
Cannot rotate a revoked or expired key. |
Gone (410)
| Code |
Type |
What it means |
embed_session_closed |
invalid_request_error |
Embed session closed (saved/abandoned); start a new one. |
embed_session_expired |
invalid_request_error |
Embed session past its TTL; start a new one. |
Size limits (413)
| Code |
Type |
What it means |
font_too_large |
invalid_request_error |
Font file exceeds the per-asset cap. |
image_too_large |
invalid_request_error |
Image file exceeds the per-asset cap. |
pdf_too_large |
invalid_request_error |
PDF upload exceeds the per-template cap. |
Media type (415)
| Code |
Type |
What it means |
unsupported_media_type |
invalid_request_error |
Request body's Content-Type isn't accepted here. |
unsupported_font_binary |
invalid_request_error |
Font file isn't OTF/TTF/WOFF/WOFF2. |
unsupported_image_type |
invalid_request_error |
Image file isn't PNG/JPG/SVG. |
Validation / idempotency (422)
| Code |
Type |
What it means |
delivery_exhausted |
invalid_request_error |
Webhook delivery already hit its 10-attempt cap. |
delivery_skipped |
invalid_request_error |
Delivery was skipped (endpoint paused at the time); not retryable. |
landscape_artwork_unavailable |
invalid_request_error |
The approved landscape transcript scene or source is unavailable for this revision. Select portrait and contact support; retrying the same request will not help. |
publishable_no_rotate |
invalid_request_error |
Publishable keys don't support rotation; revoke and create a new one. |
idempotency_key_mismatch |
idempotency_error |
Same Idempotency-Key reused with a different request body. |
Idempotency conflicts (409)
| Code |
Type |
What it means |
idempotency_request_in_progress |
idempotency_error |
Another request with this Idempotency-Key is still being processed. Retry after a short delay to pick up the cached outcome. |
Rate limit (429)
| Code |
Type |
What it means |
rate_limit_exceeded |
rate_limit_error |
Sliding-window rate limit tripped. Respect Retry-After. |
Server errors (500 / 502 / 503)
Transient unless the same code repeats. *_not_configured 503s mean an
operator needs to set a secret — see STRIPE-PRODUCTION-CHECKLIST.md
or docs/operations/.
| Code |
Type |
What it means |
internal_error |
api_error |
Handler crashed before sending a normal response. |
render_failed |
api_error |
Render pipeline crashed mid-job. |
fill_render_failed |
api_error |
A hosted fill link couldn't produce the final PDF. Written for the shop's customer (audience: "customer") with a reference (the fill id) to quote to the shop; 503 when the press renderer was unreachable after a retry (try again in a minute), 500 otherwise. The operator is alerted either way. |
ingest_failed |
api_error |
PDF ingest crashed; check the templates log in /admin. |
rotation_failed |
api_error |
API key rotation crashed mid-write. |
scene_fetch_failed |
api_error |
Couldn't load the scene row for a template. |
stripe_event_failed |
api_error |
Stripe webhook handler crashed; Stripe will retry. |
access_token_corrupt |
api_error |
Hosted-fill token couldn't be decoded; create a new fill. |
fill_context_missing |
api_error |
Fill row exists but linked template/scene is gone. |
renderer_failed |
api_error |
Ghostscript renderer container returned an error. |
renderer_unreachable |
api_error |
RENDERER_SERVICE_URL returned a network error. |
fill_team_mismatch |
invalid_request_error |
Internal — fill's team doesn't match the calling key. |
fill_template_mismatch |
invalid_request_error |
Internal — fill's template_id doesn't match the URL. |
billing_not_configured |
invalid_request_error |
Plan catalog row missing both Stripe price IDs. |
billing_plan_not_found |
invalid_request_error |
Plan row referenced by team is gone. |
db_unavailable |
service_unavailable |
D1 binding missing. |
kv_not_configured |
service_unavailable |
Required KV binding missing. |
r2_not_configured |
service_unavailable |
Required R2 binding missing. |
stripe_not_configured |
service_unavailable |
STRIPE_SECRET_KEY unset. |
stripe_webhook_secret_missing |
service_unavailable |
STRIPE_WEBHOOK_SECRET unset. |
webhook_secrets_not_configured |
service_unavailable |
Outbound webhook signing secrets unset. |
idempotency_store_unavailable |
service_unavailable |
Internal idempotency-claim store unreachable; retry shortly. |
See API reference for endpoint-level docs.