Errors

Error response format and common HTTP status codes.

Error response shape

All error responses follow a consistent JSON structure with a human-readable message and a machine-readable code.

{
  "error": {
    "message": "Human-readable error message",
    "code": "machine_readable_code"
  }
}

HTTP status codes

HTTP status	Code	Meaning
400	`validation_error`	Invalid request body or parameters.
400	`bad_request`	Request was syntactically valid but cannot be processed.
400	`unknown_project`	`X-Wonda-Project` names a project that does not exist in the active personal or org scope.
401	`unauthorized`	Missing or invalid API key.
402	`payment_required`	Payment required.
402	`insufficient_credits`	Not enough credits to complete the request.
403	`forbidden`	The account cannot access the resource or action.
403	`feature_disabled`	A feature flag or account gate is disabled for this account.
404	`not_found`	Resource not found or API not enabled for the account.
409	`conflict`	Request conflicts with the current state of the resource.
409	`project_exists`	A project with that normalized name already exists in the active scope.
410	`gone`	Endpoint or operation has been retired. The response message may include a migration hint.
429	`rate_limit_exceeded`	Too many requests.
429	`throttled`	A safety or action gate blocked the request and may include retry metadata such as `deferUntil`.
500	`internal_server_error`	Internal server error.

The code field is always present in error responses. A 400 from request validation uses validation_error; other generic 400 errors use bad_request. A 402 uses insufficient_credits when the error message mentions insufficient credits, and payment_required otherwise.

Example

{
  "error": {
    "message": "'model' is required",
    "code": "validation_error"
  }
}