Developer portal

Errors & status codes

Every failure path should be actionable for operators and engineers.

Error envelope

Typical error body

{
  "status": "error",
  "message": "Invalid API key. Check the pilot token and try again.",
  "detail": "optional string or validation object"
}

Code	Meaning	Typical cause	Suggested fix
400	Bad request	Malformed JSON or missing required headers.	Validate Content-Type and JSON syntax before retrying.
401	Unauthorized	Missing or invalid API key in Authorization or x-api-key header.	Send Bearer <key> or x-api-key with a valid pilot token.
422	Unprocessable entity	Invalid payload shape, unsupported problem type, or infeasible constraints.	Fix field errors in the response detail; relax constraints and retry.
429	Too many requests	Per-key rate limit exceeded (default 120 requests per minute).	Backoff with jitter; cache results; request a higher limit for production.
500	Internal server error	Unexpected backend failure.	Retry with exponential backoff; contact support if persistent.
501	Not implemented	Problem type not yet supported on the live solver path (routing, allocation).	Use type schedule for live jobs, or follow the roadmap for routing/allocation.