इसे छोड़कर कंटेंट पर जाएं

IZI API Error Codes

Опубликовано: · Обновлено: (1 месяц назад)· IZI Team

यह कंटेंट अभी तक आपकी भाषा में उपलब्ध नहीं है।

GraphQL API errors come back in the errors field of the response body, not via HTTP status. HTTP 200 on an error is normal. Know this so you don’t write an error handler that only checks HTTP status.

{
"data": null,
"errors": [
{
"message": "User not authenticated",
"path": ["userProfile"],
"extensions": {
"code": "Unauthorized",
"message": "User not authenticated"
}
}
]
}

Fields in extensions:

  • code — machine-readable error code (use it in switch/case)
  • message — error text, the same as the top-level message

Some errors add their own detail fields to extensions. Business errors and validation errors carry no locations field — the server parses documents with noLocation. A syntax error does carry locations, pointing at the position in the query text itself.

The exceptions to the “HTTP 200” rule are everything rejected before the operation runs:

What happenedHTTPCode
Syntax, unknown field, wrong variable type400GRAPHQL_PARSE_FAILED, GRAPHQL_VALIDATION_FAILED, BAD_USER_INPUT
An array of operations in the body (batching off)400BAD_REQUEST
Body larger than 256 KB413PAYLOAD_TOO_LARGE
Query complexity above 750500QUERY_TOO_COMPLEX

The last row is where ordinary error handling breaks: a query above 750 is rejected permanently, yet it arrives with status 500, so it looks like a server fault. Retrying it is pointless — read extensions.code, not the HTTP status.

Codes are values of the ErrorCodes enum. Base codes are written in PascalCase, codes of individual modules are often in UPPER_SNAKE_CASE. Compare the code as a whole string, without changing case.

CodeWhen
UnauthorizedToken missing, expired or invalid, and the field requires authentication
ForbiddenToken valid, but the role or the user lacks rights
NotFoundObject not found
InvalidInputInput failed validation; an operation without a name is rejected too
InternalServerErrorAn internal error the API raised itself — a broken invariant
INTERNAL_SERVER_ERRORAn unexpected server error: Apollo substitutes this code, and it is the one you will meet more often
TooManyAttemptsToo many failed sign-in attempts
AccountDeletedThe player account was deleted, its token no longer works
INSUFFICIENT_BALANCEInsufficient funds
DEVICE_OFFLINEDevice is offline

The remaining codes belong to specific modules — orders, sessions, warehouse, acquiring — and are described in the schema next to the operations that return them.

graphql-request throws when the response has errors. The code is read from extensions:

async function requestIZI(client, document, variables) {
try {
return await client.request(document, variables);
} catch (error) {
const code = error.response?.errors?.[0]?.extensions?.code;
switch (code) {
case "Unauthorized":
// Token missing or expired: there is no token refresh, sign in again
throw new SessionExpiredError(error.message);
case "Forbidden":
throw new PermissionError(error.message);
case "NotFound":
throw new NotFoundError(error.message);
default:
throw new IZIError(code, error.message);
}
}
}

अक्सर पूछे जाने वाले सवाल

Why does the IZI API return HTTP 200 even on errors?

This is standard GraphQL behavior. HTTP 200 means the request was received and processed. Business errors come back in the errors field of the response body. Handle both cases.

What is the difference between Forbidden and Unauthorized?

Unauthorized — the token is missing, expired or invalid, and the field requires authentication. Forbidden — the token is valid, but the role or the user lacks the rights for the operation.

Where do I get the full list of codes?

Codes are the values of the ErrorCodes enum in the GraphQL schema, about 350 of them. Introspection is disabled on the contours, so request the current schema (SDL) from IZI.

About IZI