Обработка ошибок

Каждый метод сервиса возвращает обычный error. Сбои на транспортном уровне (DNS, отказ соединения, таймаут) возвращаются обёрнутыми в fmt.Errorf; всё, что отклонил сам API Z.AI, возвращается как *client.APIError со структурированными полями, по которым можно ветвить логику, вместо разбора строк сообщения.

resp, err := c.Chat().Create(ctx, req)
if err != nil {
    var apiErr *client.APIError
    if errors.As(err, &apiErr) {
        fmt.Printf("[%d] %s\n", apiErr.Code, apiErr.UserMessage)

        switch apiErr.Category {
        case client.ErrorCategoryAuth:
            // bad/expired key — don't retry, tell the user
        case client.ErrorCategoryQuota:
            // out of balance/quota — don't retry, surface to the user
        case client.ErrorCategoryRateLimit:
            if apiErr.IsRetriable {
                // the client already retries this internally up to
                // Config.MaxRetries — you'll only see it here if retries
                // were exhausted or disabled (MaxRetries: -1)
            }
        }
        return
    }
    // transport-level failure — network, DNS, timeout
}

Поля APIError:

Вспомогательные предикаты: IsAuthError(), IsRateLimitError(), IsQuotaError(), IsParameterError(), IsServerError() — эквивалентны прямой проверке .Category, предоставлены для читаемости в местах вызова.

Поведение повторов из коробки

Client.doRequest (используется каждым сервисом) уже повторяет ошибки 429/5xx/сети с экспоненциальной задержкой, джиттером и поддержкой Retry-After, до Config.MaxRetries (по умолчанию 3; установите -1 для отключения). Обычно вам не нужен собственный цикл повторов — APIError.IsRetriable подскажет, исчерпала ли ошибка, дошедшая до вашего кода, эти повторные попытки.

Справочник кодов ошибок

Код ошибки, неизвестный этому клиенту, по умолчанию получает ErrorCategoryServer с IsRetriable: true — разумное значение по умолчанию (неизвестные коды трактуются как временные проблемы сервера), но именно для перечисленных выше констант задано специально подобранное UserMessage и решение о повторе.

Источник истины: pkg/client/errors.go.

Особенность: 200 со встроенным сбоем

Несколько эндпоинтов (Invoke/AsyncResult у агентов) возвращают HTTP 200 даже в случае неудачи на бизнес-уровне — сбой встроен в тело ответа, а не сигнализируется через HTTP-статус. Ненулевой error из этих методов означает, что не сработал транспортный уровень; для обнаружения сбоя на бизнес-уровне внутри успешного ответа проверяйте resp.Failed() (или напрямую resp.Error/ resp.Status). Оба типа ответов документируют это в методе Failed() — легко пропустить, если проверять только err != nil.