Troubleshooting

On this page

Error response formatCommon error codesRate limitsDispatch and 502sMore help

Error response format

Errors return JSON in this shape:

{
  "error": "Short message",
  "code": "ERROR_CODE",
  "details": null,
  "hint": "Optional suggestion"
}

Use code for programmatic handling; hint and details for debugging.

Common error codes

Code HTTP Cause What to do
VALIDATION_ERROR 400 Invalid or malformed request body/params Check schema (e.g. name format, required fields). See OpenAPI or Deploy and rollback.
TENANT_NOT_FOUND 404 Organization not found in database Sign up to create an organization, or check that the tenant_id is correct.
FUNCTION_NOT_FOUND 404 No function for ID, or no deployed function for subdomain Deploy a function for that organization or use the correct function_id.
BINDING_NOT_FOUND 400 Requested binding (e.g. key-value:name) not in bindings table Ask your team admin to create the binding, or fix the binding spec in your deploy intent.
BINDING_NOT_ALLOWED 403 Binding not allowed for organization Ensure the binding exists and is in the organization's allowed_bindings.
CODE_INVALID 400 Script failed validation/bundling Fix syntax or structure; ensure default export.
DEPLOY_FAILED 502 Upload or platform step failed Retry; check platform status.
ROLLBACK_FAILED / VERSION_NOT_FOUND 502/404 Rollback target missing or upload failed Use a version that exists (from list functions or activations).
RATE_LIMITED 429 Too many requests to subdomain Wait and retry; default limit is 100 req/min per organization (configurable).
DISPATCH_FAILED 502 Function execution failed Check your code and platform status.
USAGE_LIMIT_EXCEEDED 429 Monthly usage cap reached (Free plan) Wait for the next billing period, or upgrade to Pro for soft caps. See Billing.
PRO_PLAN_REQUIRED 403 Feature requires Pro plan (custom domains, AI) Upgrade to Pro from the billing page.
DOWNGRADE_BLOCKED 409 Current usage exceeds Free plan limits Reduce functions, team members, or storage before downgrading.
FORBIDDEN 403 Wrong role or organization scope Use a token with the right role; deployers only access their organization.
AUTH_REQUIRED 401 No token sent Send Authorization: Bearer <token>.
AUTH_INVALID 401 Invalid or expired token Re-login or get a new token.

Rate limits

  • Organization subdomain: Configurable per organization (default 100 requests per minute). Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. When exceeded you get 429 and code: RATE_LIMITED.

Other endpoints may have limits; if so they are documented in the API or returned in response headers.

Dispatch and 502s

  • DISPATCH_FAILED: The request reached the platform but the function invocation failed. Check your code (errors, timeouts) and any bindings/secrets. Use get_activation_logs or GET /activations to see error_message and response_status.
  • If the platform returns 501 with something like DISPATCH_NOT_CONFIGURED, the dispatch namespace is not set up; contact the platform operator.

More help

PreviousError reference