Errors

The API uses standard HTTP status codes. The body always follows the response envelope with success: false.

Status codes

Status	When	Body
400	The X-CANTEEN-ORGANIZATION header is missing, or the request is malformed.	{ "success": false, "message": "Invalid request data." }
401	No token, or a revoked one.	{ "success": false, "message": "Unauthorized. Please provide a valid token." }
403	The token is valid but its user is not a member of the organization, or the organization is inactive.	{ "success": false, "message": "You do not have permission to access this resource." }
404	Unknown organization UUID, or a filter references a UUID that does not exist.	{ "success": false, "message": "Resource not found." }
422	A query parameter failed validation.	See below.
429	Rate limit exceeded. See Rate limits.	{ "success": false, "message": "Too many requests. Please try again later." }
500	Something failed on our side. We are notified automatically.	{ "success": false, "message": "An unexpected error occurred. Error Code: 500" }

Validation errors

A 422 explains which parameters were rejected and why. Keys in errors match the parameter names.

{
  "success": false,
  "message": "Validation failed.",
  "errors": {
    "status": ["The selected status is invalid."],
    "end_date": ["The end date field must be a date after or equal to start date."]
  }
}

What to retry

• 429 and 5xx: retry with a backoff. Honour Retry-After on 429.
• 400, 401, 403, 404, 422: do not retry. The same request will fail the same way until something changes on your side or ours.

Getting help

When you report a problem, include the full request (minus the token), the response body and the time of the call in UTC. That is enough for us to find it in our logs.