Skip to main content

Error Response Format

All API errors return JSON with a consistent structure. Error messages are written in a conversational tone — they tell you what went wrong and often include a hint field with a suggestion for how to fix it.
Some errors also include contextual fields like upgrade with actionable next steps (e.g., a checkout endpoint to call). Some publishing errors also include structured remediation details so an agent can recover safely.

Error Codes

Common Scenarios

Invalid API Key

Fix: Check that your API key starts with sh_live_ and is complete (no truncation).

Rate Limited

Fix: Wait until the time indicated by the X-RateLimit-Reset header. See Rate Limits.

Storage Exceeded

Fix: Delete unused sites to free storage, or upgrade to the Hobby plan for 100 GB.

File Path Invalid

Fix: File paths must be relative (no leading /), cannot contain .., and must be under 500 characters.

Exposed Secret Detected During Publish

Fix: Do not publish the site as-is. Ask the user for permission, move the secret into Site Variables, approve the destination in Proxy Host Allowlist, update only the published output to use the Site Proxy, and then retry finalize.