All HTTP status codes returned by the ZPL API — with causes, fixes, and example responses. Last updated April 2026.
Request succeeded. The response body contains the computation result, resource data, or confirmation message.
{ "p_output": 0.514286, "deviation_from_0_5": 0.014286, "N": 9, "samples": 100, "bias": 0.5, "status": "STABLE" }
A new resource was created successfully. Returned by POST /auth/register, POST /keys/create, POST /newsletter/subscribe, etc.
The request was malformed or contained invalid parameters.
Validate your request parameters. Check the API Reference for parameter constraints.
{ "detail": "N must be between 3 and 64" }
Authentication failed. Either no credentials were provided or they are invalid.
Authorization: Bearer <token> headerX-Api-Key: zpl_xxxx... headerRe-login to get a fresh JWT token. For API key issues, check your Dashboard to verify the key is active. Include the header: X-Api-Key: zpl_yourkey or Authorization: Bearer <token>
{ "detail": "Invalid or expired token" }
Your account has exceeded its monthly quota for this endpoint. This is the primary billing-related error in the ZPL API.
1. Wait: limits reset on the 1st of the next calendar month.
2. Top-up: purchase extra calls from our Top-ups section (€4.99–€299.99).
3. Upgrade plan: switch to a higher tier for permanently larger monthly limits.
{ "detail": "Monthly rate limit exceeded. Upgrade your plan or purchase a top-up." }
The request is valid but not permitted for your account's plan or role.
Check your plan's limits on the Pricing page. Upgrade to use larger N values or premium features. For scope issues, create a new API key with the required scope.
{ "detail": "N=32 exceeds your plan limit (max N=9). Upgrade to use larger matrices." }
The requested resource does not exist.
Double-check the endpoint path in the API Reference. Verify that the resource ID exists in your Dashboard.
The request body was syntactically valid JSON but failed semantic validation (Pydantic model validation).
Check the detail array in the response — it contains specific field-level error messages from Pydantic.
{ "detail": [{ "loc": ["body", "N"], "msg": "value is not a valid integer", "type": "type_error.integer" }] }
You have exceeded a short-term rate limit (distinct from the 402 monthly quota limit).
Wait for the rate limit window to expire. For auth failures, check your credentials carefully before retrying. For API calls requiring no rate limits, use an API key.
{ "detail": "Too many login attempts. Try again in 15 minutes." }
An unexpected error occurred on the server side. This is not caused by your request.
Retry the request after a few seconds. If the error persists, check our System Status page and contact support with your request details.
{ "detail": "ZPL computation error: ..." }
The feature exists in the API but is not configured on this deployment.
Check the Status page to see which features are enabled. Use an alternative authentication method.
The server is temporarily unavailable. Usually happens during deployment or after the free-tier cold start.
Wait 30–60 seconds and retry. For production workloads, use an API key with a plan that keeps the server warm. Check system status for ongoing incidents.
The monthly quota resets automatically on the 1st of each calendar month at midnight UTC. Your counter goes back to zero and all requests are permitted again (until the new month's limit is reached).
Log in to your Dashboard to see current month usage, quota, and days until reset.
When you create an API key, you assign it a scope: full, compute, ai, or read-only. Using a key for an endpoint outside its scope returns 403.
"full": all endpoints "compute": /compute, /sweep only "ai": /ai/* only "read-only": GET requests only
Create a new API key with the correct scope for your use case in the Dashboard.