IZI API Error Codes

IZI API Error Codes

Errors in the GraphQL API are returned in the errors field of the response body, not via HTTP status. HTTP 200 on an error is normal. Knowing this upfront prevents writing a handler that only checks HTTP codes.

Error Structure

{
  "data": null,
  "errors": [
    {
      "message": "Token is expired",
      "extensions": {
        "code": "TOKEN_EXPIRED",
        "timestamp": "2026-05-30T14:32:00Z"
      },
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["me"]
    }
  ]
}

Fields in extensions:

• code — machine-readable error code (use in switch/case)
• timestamp — server-side error time
• field — field that caused the error (when applicable)
• details — additional context (not always present)

Auth Error Codes

Code	HTTP	Description	Action
UNAUTHENTICATED	401	Token missing or not provided	Add Authorization: Bearer <token> header
TOKEN_EXPIRED	401	accessToken expired	Refresh via refreshToken mutation
REFRESH_TOKEN_EXPIRED	401	refreshToken expired	Re-login via loginWithEmailPassword
TOKEN_INVALID	401	Token corrupted or forged	Check that the token hasn’t been truncated or modified
FORBIDDEN	403	No permission for the operation	Check user role
CLUB_ACCESS_DENIED	403	No access to this club	Check user’s club assignment

Data Error Codes

Code	Description	Action
NOT_FOUND	Object doesn’t exist or belongs to another organization	Check ID and organization ownership
ALREADY_EXISTS	Duplicate on creation	Check unique fields (email, phone)
VALIDATION_ERROR	Data failed validation	Check details field in extensions
INVALID_INPUT	Wrong input format	Check against the GraphQL schema

Business Logic Error Codes

Code	Description	Action
INSUFFICIENT_BALANCE	Not enough funds	Check balance before the operation
SESSION_ALREADY_ACTIVE	Device already has an active session	End the current session via endSession
DEVICE_OFFLINE	Device is not online	Check device status via deviceStatus
TARIFF_NOT_AVAILABLE	Tariff unavailable (schedule, zone)	Check tariff conditions
CLUB_CLOSED	Club is closed (no open shift)	Open a shift in the CRM
CLIENT_BLACKLISTED	Client is blacklisted	Contact the club admin
PAYMENT_FAILED	Payment gateway error	Check details for the acquirer error code
WEBHOOK_URL_UNREACHABLE	Webhook URL unreachable during check	Make sure endpoint responds to GET

Infrastructure Error Codes

Code	HTTP	Description	Action
RATE_LIMIT_EXCEEDED	429	Request limit exceeded	Wait Retry-After seconds
INTERNAL_SERVER_ERROR	500	Internal server error	Retry. If it persists — contact IZI support
SERVICE_UNAVAILABLE	503	Service temporarily unavailable	Exponential backoff

Error Handling in Code

async function handleIZIRequest(query, variables) {
  const response = await client.request(query, variables);

  if (response.errors) {
    for (const error of response.errors) {
      const code = error.extensions?.code;

      switch (code) {
        case 'TOKEN_EXPIRED':
          await refreshTokens();
          return handleIZIRequest(query, variables);

        case 'RATE_LIMIT_EXCEEDED':
          const retryAfter = error.extensions?.retryAfter || 5;
          await sleep(retryAfter * 1000);
          return handleIZIRequest(query, variables);

        case 'NOT_FOUND':
          throw new NotFoundError(error.message);

        case 'FORBIDDEN':
          throw new PermissionError(error.message);

        default:
          throw new IZIError(code, error.message, error.extensions);
      }
    }
  }

  return response.data;
}

Validation Errors

For VALIDATION_ERROR, extensions.details contains a field list:

{
  "code": "VALIDATION_ERROR",
  "details": [
    {
      "field": "input.amount",
      "message": "Must be positive number",
      "constraint": "min",
      "value": -100
    }
  ]
}

Related Pages

• Authentication & Tokens — auth errors in detail
• Rate Limits — about 429 and backoff
• SDK Examples — ready error handlers