Docs/Overview
Docs/Error Codes Reference

Error Codes Reference

Deterministic, actionable error codes returned by the Exovon control plane and Edge Router. Every code specifies the failure condition, request ID, and recommended mitigation.

HTTP Status Codes

Standard status codes emitted by edge proxies and container runtimes:

StatusSemantic MeaningTrigger ConditionRecommended Resolution
200OKRequest executed successfully.Normal operation.
400Bad RequestMalformed payload, invalid parameters, or syntax validation error.Verify request body schema against API documentation.
401UnauthorizedMissing, invalid, or expired API authentication token.Verify Authorization header: Bearer exo_live_...
403ForbiddenAuthenticated account lacks permission to mutate resource.Verify project ownership and token scope permissions.
413Payload Too LargeRequest body exceeds tier upload quota (Free 3MB, Starter 4MB, Pro 6.5MB).Compress payload or upload large binaries directly to Object Storage.
429Too Many RequestsRate limit or concurrency envelope exceeded.Implement exponential backoff based on the Retry-After header.
500Internal Server ErrorUnhandled container exception or runtime failure.Inspect server stderr logs in project dashboard.
504Gateway TimeoutContainer execution exceeded plan duration limit.Optimize slow queries or offload long-running tasks to background jobs.

Build & Deployment Codes

Codes returned by the build runner engine:

Error CodeConditionRoot Cause & Resolution
BUILD_TIMEOUTCompilation duration exceeded plan thresholdCache dependencies or optimize compile scripts. Limits: Free 5m, Starter 15m, Pro 30m.
BUILD_FAILEDBuild process exited with non-zero codeCheck build logs. Common issues: missing dependencies, TypeScript syntax errors, missing env vars.
STATIC_ASSET_LIMIT_EXCEEDEDStatic files breach Fair Use size, count, or format boundariesFiles exceed plan limits (25 MB Free / 50 MB Paid per file, 5,000 / 25,000 files, 100 MB / 5 GB total site), or contain prohibited video/archive media. Host large media in Exovon Object Storage.
MEMORY_LIMITProcess exceeded container RAM allocationOptimize memory usage or upgrade tier (Free: 512MB, Starter/Pro: 1GB, Heavy: 4GB+).
STARTUP_FAILEDContainer crashed during initial boot health probeVerify server start script and confirm your app binds to PORT=8080.
DEPLOY_RATE_LIMITMonthly build execution minutes exhaustedWait for next monthly quota reset (1st of month) or upgrade plan.

Database Error Codes

Error codes emitted by ExoStore PostgreSQL connection proxies and query engines:

Error CodeConditionRecommended Resolution
DB_CONNECTION_LIMITPostgreSQL connection pool exhaustedConnect using the pooled endpoint (Port 6543) or switch to the stateless @neondatabase/serverless HTTP driver.
DB_TIMEOUTQuery execution exceeded 30-second timeoutAdd indexes on queried columns, optimize unindexed JOINs, or run heavy reporting queries asynchronously.
DB_STORAGE_FULLDatabase storage exceeded plan allocationVacuum tables, remove obsolete temporary branches, or upgrade your plan storage tier.

Quota & Resource Limit Codes

Codes returned when project consumption reaches tier boundary thresholds:

Error CodeConditionPlatform Action & Fix
BANDWIDTH_EXHAUSTEDMonthly origin bandwidth allowance reachedEdge router applies soft rate-limiting with a 48-hour grace window. Live sites stay online; upgrade to restore unthrottled traffic.
STORAGE_LIMITBuild artifact storage capacity reachedClean up old deployment builds in dashboard or upgrade to expand storage capacity.
PROJECT_LIMITMaximum projects per account reachedFree tier allows 1 project, Starter allows 5, Pro allows 10. Upgrade tier to provision additional projects.

Standard JSON Error Envelope

All API errors adhere to a deterministic JSON payload schema:

JSON Error Envelope
{
  "error": {
    "code": "BUILD_TIMEOUT",
    "message": "Build exceeded the 30-minute timeout for your Pro plan.",
    "details": {
      "plan": "Pro",
      "limit": "30 minutes",
      "actual": "32 minutes 14 seconds"
    },
    "request_id": "req_8f3a9b2c1d4e",
    "timestamp": "2026-08-09T00:29:00Z"
  }
}