Error responses

Every YumKiosk API returns errors in a consistent shape so clients can handle them generically. We use standard HTTP status codes for transport-level issues and include a machine-readable error code + human message in the body for application-level issues. This page lists the error shape, the status code conventions, and the full catalog of error codes you may see.

#The error shape

Every error response body looks like this:

{
  "error": {
    "code": "SESSION_NOT_FOUND",
    "message": "No session exists with the given ID.",
    "request_id": "req_8f2c1a",
    "details": {
      "session_id": "ses_abc123"
    }
  }
}

Fields:

• code — a machine-readable enum. Stable. Clients should branch on this.
• message — a human-readable English sentence. Useful for logging, but don't parse it. Subject to wording changes at any time.
• request_id — a unique ID for this request. Include it in any support ticket.
• details — optional object with context-specific extra information. Schema varies by error code.

#Status code conventions

• 200 — success
• 201 — resource created
• 204 — success, no content (DELETE)
• 400 — malformed request (bad JSON, missing required field, wrong types)
• 401 — missing or invalid credentials
• 403 — credentials valid but not authorized for this resource
• 404 — resource doesn't exist (or doesn't exist for this account)
• 409 — conflict (e.g., trying to accept a session that was already accepted)
• 422 — validation failure on otherwise valid request
• 429 — rate limited
• 500 — unexpected server error
• 502/503 — temporary platform issue, retryable

Anything in the 5xx range is a bug on our side. Retry with exponential backoff and if it persists, email support@yumkiosk.com with the request_id.

#422 validation errors

For 422 responses from form-style endpoints (login, signup, order placement), the body format is slightly richer to accommodate Laravel's built-in validator:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The given data was invalid.",
    "errors": {
      "email": ["The email field is required."],
      "password": ["The password must be at least 12 characters."]
    }
  }
}

The errors object maps field names to arrays of error messages. Surface these directly to your UI.

#Error code catalog

#Authentication

• UNAUTHORIZED — no credentials provided
• INVALID_CREDENTIALS — wrong email or password
• DEVICE_TOKEN_INVALID — the device token is revoked or expired
• CSRF_MISMATCH — the X-XSRF-TOKEN header doesn't match the cookie
• SESSION_EXPIRED — login session timed out

#Pairing

• PAIRING_CODE_EXPIRED — code is older than 15 minutes
• PAIRING_CODE_ALREADY_USED — another device has claimed it
• PAIRING_CODE_NOT_FOUND — wrong code

#Sessions

• SESSION_NOT_FOUND — no session with that ID, or not visible to this agent
• SESSION_ALREADY_ACCEPTED — another agent got there first (409)
• SESSION_ALREADY_ENDED — trying to modify a closed session
• SESSION_NOT_YOURS — trying to end a session you didn't accept

#Orders

• MENU_ITEM_NOT_FOUND — the item ID doesn't exist or is inactive
• MODIFIER_REQUIRED — tried to add an item without required modifiers
• INVALID_QUANTITY — quantity <= 0

#Billing

• PAYMENT_METHOD_REQUIRED — attempted a paid action without Stripe on file
• PAYMENT_FAILED — Stripe rejected the charge
• SUBSCRIPTION_CANCELLED — owner's subscription is no longer active

#Rate limits

• RATE_LIMITED — see Rate limits

#Generic

• VALIDATION_FAILED — 422 validation errors, see details
• INTERNAL_ERROR — server bug, include request_id in support ticket
• SERVICE_UNAVAILABLE — temporary downtime, retry later

#Debugging

For any error, start by checking the request_id in your logs. We can look it up on our side and tell you exactly what happened — what the server received, what branched where, what was in the database at that moment. request_id is the single most useful piece of information in a support ticket.

If you're running in development and want to see stack traces inline instead of sanitized errors, set APP_DEBUG=true in your local environment. Never do this in production — it leaks implementation details that can be used to attack your deployment.