Errors

Error responses use Content-Type: application/problem+json following RFC 9457.

Problem details shape

{
  "type": "https://cowtic.com/problems/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/orders",
  "requestId": "8f3c…",
  "errors": [
    { "path": "customer.email", "message": "Invalid email" }
  ]
}

Field	Meaning
`type`	Stable URI identifying the problem class
`title`	Short, human-readable summary
`status`	HTTP status code
`detail`	Optional explanation for this occurrence
`instance`	Request path
`requestId`	Correlation id (also in `X-Request-Id`)
`errors`	Optional field-level validation issues

Common problem types

Status	`type` suffix	When
`400`	`bad-request` / `validation-error`	Invalid input or business rule
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	Authenticated but missing scope
`404`	`not-found`	Resource not in this organization
`409`	`idempotency-conflict`	Idempotency-Key reused with different body
`429`	`rate-limited`	Rate limit exceeded
`500`	`internal-error`	Unexpected server failure

Full URIs look like https://cowtic.com/problems/not-found.

Client handling

Branch on status (and optionally type) — not on free-text detail.
Surface errors[] for form validation when present.
Log requestId for support.
For 429, honor Retry-After — see Rate limits.

Errors

Problem details shape

Common problem types

Client handling

On this page