Errors

Error Response Format

All error responses follow a consistent format:


{
  "error": {
    "message": "Human-readable error message",
    "code": "ERROR_CODE",
    "details": {}
  }
}

HTTP Status Codes

Code	Description
`400`	Bad Request — Invalid parameters or request body
`401`	Unauthorized — Missing or invalid authentication
`403`	Forbidden — Insufficient permissions or scope
`404`	Not Found — Resource doesn’t exist or isn’t accessible
`409`	Conflict — Resource already exists or state conflict
`422`	Unprocessable Entity — Validation failed
`429`	Too Many Requests — Rate limit exceeded
`500`	Internal Server Error — Something went wrong on our end

Common Error Codes

Code	Description
`VALIDATION_ERROR`	Request body failed Zod validation
`NOT_FOUND`	The requested resource was not found
`UNAUTHORIZED`	Authentication required
`FORBIDDEN`	Insufficient permissions
`CONFLICT`	Resource already exists
`RATE_LIMITED`	Too many requests

Validation Errors

When validation fails (422), the details field contains specific field errors:


{
  "error": {
    "message": "Validation failed",
    "code": "VALIDATION_ERROR",
    "details": {
      "issues": [
        { "path": ["name"], "message": "Required" },
        { "path": ["email"], "message": "Invalid email" }
      ]
    }
  }
}