IZI API Error Codes
Ce contenu n’est pas encore disponible dans votre langue.
IZI API Error Codes
Section titled “IZI API Error Codes”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.
Error Structure
Section titled “Error Structure”{ "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-levelmessage
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 happened | HTTP | Code |
|---|---|---|
| Syntax, unknown field, wrong variable type | 400 | GRAPHQL_PARSE_FAILED, GRAPHQL_VALIDATION_FAILED, BAD_USER_INPUT |
| An array of operations in the body (batching off) | 400 | BAD_REQUEST |
| Body larger than 256 KB | 413 | PAYLOAD_TOO_LARGE |
| Query complexity above 750 | 500 | QUERY_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.
Common Codes
Section titled “Common Codes”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.
| Code | When |
|---|---|
Unauthorized | Token missing, expired or invalid, and the field requires authentication |
Forbidden | Token valid, but the role or the user lacks rights |
NotFound | Object not found |
InvalidInput | Input failed validation; an operation without a name is rejected too |
InternalServerError | An internal error the API raised itself — a broken invariant |
INTERNAL_SERVER_ERROR | An unexpected server error: Apollo substitutes this code, and it is the one you will meet more often |
TooManyAttempts | Too many failed sign-in attempts |
AccountDeleted | The player account was deleted, its token no longer works |
INSUFFICIENT_BALANCE | Insufficient funds |
DEVICE_OFFLINE | Device 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.
Error Handling in Code
Section titled “Error Handling in Code”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); } }}Related Pages
Section titled “Related Pages”- Authentication & Tokens — sign-in errors in detail
- SDK Examples — ready wrappers in JS and Python
Questions fréquentes
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.
IZI LLC (ООО «ИЗИ»), TIN 7842227686, OGRN 1257800012249, office 1, premises 3-N, lit. A, 15-17 Perekupnoy lane, Saint Petersburg, 191024, Russia, admin@izi.is · Cookie settings