Errors¶

The current OpenAPI contract explicitly documents validation errors. Other error classes should still be documented before the API reference is considered complete.

Documented error type¶

Validation failures are returned as 422 Unprocessable Entity with this shape:

{
  "detail": [
    {
      "loc": ["body", "address"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Validation error fields¶

loc: where the validation failed
msg: human-readable explanation
type: machine-readable error type
input: optional original input
ctx: optional structured context

Common reasons for `422`¶

Missing required fields
Invalid UUID values
Invalid date-time values
Enum values outside the documented allowed set
String or integer values outside documented length or range constraints

Examples¶

Invalid session creation request:

curl -sS -X POST "https://app.vulnetic.ai/api/v1/sessions" \
  -H "<AUTH_HEADER_NAME>: YOUR_API_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -d '{}'

Example response:

{
  "detail": [
    {
      "loc": ["body", "address"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

What still needs to be published¶

Warning

The current spec does not yet model the rest of the production error surface, including auth failures, permission failures, not-found responses, conflict conditions, or internal server errors.

Before public release, add the exact status codes and response schemas for:

401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict, if lifecycle transitions can be invalid for current state
429 Too Many Requests, if rate limiting is enforced
5xx server failures