Skip to content

Error Codes

API error responses and their meanings.

Error Response Format

{
  "code": "ERROR_CODE",
  "message": "Human-readable message",
  "errors": {
    "fieldName": ["Validation error 1", "Validation error 2"]
  },
  "correlationId": "abc-123-def"
}
Field Description
code Machine-readable error code
message Human-readable description
errors Field-specific validation errors
correlationId Request tracking ID for debugging

HTTP Status Codes

Status Meaning When Used
400 Bad Request Validation errors
401 Unauthorized Missing/invalid token
403 Forbidden Insufficient permissions
404 Not Found Resource doesn't exist
409 Conflict Concurrency conflict
429 Too Many Requests Rate limit exceeded
500 Server Error Unexpected error

Validation Errors (400)

Returned when request validation fails:

{
  "code": "VALIDATION_ERROR",
  "message": "One or more validation errors occurred",
  "errors": {
    "title": ["Title is required"],
    "amount": ["Amount must be greater than 0"]
  }
}

Authentication Errors (401)

Code Description
INVALID_CREDENTIALS Wrong username or password
EMAIL_NOT_CONFIRMED Email not yet confirmed
TOKEN_EXPIRED Access token has expired
TOKEN_INVALID Malformed or invalid token
REFRESH_TOKEN_EXPIRED Refresh token has expired
REFRESH_TOKEN_REVOKED Refresh token was revoked
INVALID_REFRESH_TOKEN Refresh token invalid or expired
INVALID_RESET_TOKEN Password reset token invalid
RESET_TOKEN_EXPIRED Password reset token expired

Authorization Errors (403)

Code Description
FORBIDDEN User lacks permission
ACCOUNT_PENDING Account awaiting admin approval
ACCOUNT_DECLINED Account was declined
ACCOUNT_DEACTIVATED Account was deactivated
NO_GROUP User not assigned to a group
GROUP_DELETED User's group was deleted

Not Found Errors (404)

Code Description
NOT_FOUND Resource doesn't exist or was deleted

Conflict Errors (409)

Code Description
CONCURRENCY_CONFLICT Resource was modified by another request
DUPLICATE_ENTRY Unique constraint violation

Rate Limit Errors (429)

Code Description
RATE_LIMIT_EXCEEDED Too many requests, try again later

Handling Errors (Frontend)

const handleError = (error: ApiError) => {
  switch (error.code) {
    case "CONCURRENCY_CONFLICT":
      // Refresh and retry
      break;
    case "TOKEN_EXPIRED":
      // Attempt refresh
      break;
    default:
    // Show error message
  }
};