Error Responses

All API error responses return a JSON object with a message field and the application/json content type.

Response Structure

Every error response contains:

Field	Type	Description
message	string	A human-readable explanation of the error.

Additional Fields

Depending on the error type, extra fields may be present:

Field	Type	When Present
errors	object	Validation errors (422). Keys are field names, values are arrays of error messages.

Examples

401 Unauthorized

Returned when authentication is missing or invalid.

{
  "message": "Unauthenticated."
}

403 Forbidden

Returned when the authenticated user is not authorized for the action.

{
  "message": "Access denied for authenticated users."
}

404 Not Found

Returned when the requested resource does not exist.

{
  "message": "The requested resource was not found."
}

409 Conflict

Returned when the action conflicts with the current resource state (e.g., invalid state transition).

{
  "message": "Cannot transition testimony from completed to accepted."
}

422 Unprocessable Content

Returned when validation fails. Includes an errors object with per-field messages.

{
  "message": "The email field must be a valid email address. (and 2 more errors)",
  "errors": {
    "email": [
      "The email field must be a valid email address."
    ],
    "password": [
      "The password field must be at least 8 characters.",
      "The password field confirmation does not match."
    ]
  }
}

500 Internal Server Error

Returned when an unexpected server error occurs. The message is masked in production.

Production:

{
  "message": "An unexpected error occurred."
}

Non-production (includes the actual exception message):

{
  "message": "SQLSTATE[42S02]: Base table or view not found..."
}

Content Type

All error responses are returned with the header:

Content-Type: application/json