Error Handling¶

When a request fails, check its HTTP status and error code. Cowculator returns errors in this JSON format:

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "loc": ["body", "fighter_1", "active_skills", 0, "energy_cost"],
      "message": "Input should be greater than or equal to 0",
      "type": "greater_than_equal"
    }
  ]
}

code: A stable value your app can check.
message: A short explanation for people to read.
details: Optional. Lists invalid fields when request validation fails. Each entry has a loc (field path), message, and type. Numbers in loc are array positions, so 0 above means the first active skill.

Error codes¶

HTTP status	`code`	Meaning
422	`VALIDATION_ERROR`	The request has invalid fields or invalid JSON.
422	`BATTLE_NUMERIC_LIMIT`	The battle exceeds a known calculation limit.
404	`NOT_FOUND`	The requested API path does not exist.
405	`METHOD_NOT_ALLOWED`	The path does not allow that HTTP method. Check the `Allow` header.
500	`INTERNAL_ERROR`	An unexpected server or calculation failure occurred.
Other intentional HTTP errors	`HTTP_ERROR`	Another error returned by the application.

For example, a known numeric limit returns HTTP 422:

{
  "code": "BATTLE_NUMERIC_LIMIT",
  "message": "Battle configuration exceeds supported numeric limits"
}

It has no details because there may be no single invalid field. Unexpected calculation failures return HTTP 500, not 422. The server does not return internal exception details.

Updating older clients¶

This is a breaking change. Cowculator no longer returns errors under response.detail.

Check the HTTP status and response.code.
For VALIDATION_ERROR, read response.details to show field errors.
Do not check the wording of response.message. It may change.

For exact request fields and endpoint responses, see the OpenAPI reference or the raw OpenAPI schema.