Error Reference

All API errors follow a consistent JSON shape. This page lists every HTTP status code the app can return and what causes it.

Standard Error Shape

{
  "message": "Human-readable explanation."
}

Validation errors (422) include a field-level errors map:

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

HTTP Status Code Reference

Code	Name	Common Causes
`200`	OK	Successful GET / PATCH / DELETE
`201`	Created	Successful POST that created a resource
`400`	Bad Request	Invalid signed URL (email verify)
`401`	Unauthorized	Missing or invalid `Authorization: Bearer` header
`403`	Forbidden	Valid token but wrong role, or account banned / inactive
`404`	Not Found	Resource does not exist (or is soft-deleted)
`409`	Conflict	Slot already taken (indoor game / court booking)
`422`	Unprocessable Entity	Validation failure — see `errors` map
`429`	Too Many Requests	Rate limit hit (auth / OTP endpoints)
`500`	Internal Server Error	Unexpected server-side error

Domain-Specific Errors

Auth

Scenario	Status	`message`
Wrong password / inactive account	`403`	`"Invalid credentials."`
OTP expired or invalid	`422`	`"Invalid or expired OTP."`
Unsupported social provider	`422`	`"Unsupported social provider."`

Bookings

Scenario	Status	`message`
Court not available for requested slot	`409`	`"The court is not available for the selected time slot."`
Cancel a non-cancellable booking	`403`	policy-based message

Indoor Games

Scenario	Status	`message`
Slot unavailable	`409`	`"The selected slot is not available."`
Game inactive	`404`	—

Payments

Scenario	Status	`message`
Gateway callback verification fail	`422`	`"Payment verification failed."`

Coupons

Scenario	Status	`message`
Invalid / expired code	`422`	message from server

Tips for Mobile Devs

Always display message to the user when status >= 400.
For 422, iterate errors and show field-level hints inline on the form.
For 429, back off and show "Too many attempts, please wait."
For 401, clear local token and redirect to login.
For 409 on bookings, reload availability calendar and highlight taken slots.