Skip to content

docs(go-sdk): clarify intermediary error handling #198

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ysyneu merged 1 commit into from
Jul 22, 2026
Merged

docs(go-sdk): clarify intermediary error handling #198

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion en/developer/go-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,10 +249,14 @@ for page := 0; page < 100; page++ {

---

Any unsuccessful call — whether the envelope carries an error or the HTTP status is non-2xx — returns `*ErrorResponse`. It has `Code`, `Message`, and `RequestID` fields; when troubleshooting, give `RequestID` to the support team to pinpoint the request.
An unsuccessful call returned by the Flashduty API — whether the envelope carries an error or the HTTP status is non-2xx — returns `*ErrorResponse`. It has `Code`, `Message`, and `RequestID` fields; when troubleshooting, give `RequestID` to the support team to pinpoint the request.

When the API returns 429, the error is promoted to `*RateLimitError`: it embeds `*ErrorResponse` (so `errors.As` for `*ErrorResponse` still matches) and additionally carries a `RetryAfter` hint.

<Note>
If you receive a non-2xx response with a non-JSON body, the SDK returns a plain `error`, not `*ErrorResponse`. This indicates that a gateway, load balancer, proxy, or other intermediary produced the response, usually because the request exceeded an intermediary timeout. Retry the request or split a long-running batch into smaller batches, and do not assume that `errors.As(err, &apiErr)` matches this error.
</Note>

```go
_, _, err := client.Incidents.Info(ctx, &flashduty.IncidentInfoRequest{
IncidentID: "does-not-exist",
Expand Down
6 changes: 5 additions & 1 deletion zh/developer/go-sdk.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,10 +249,14 @@ for page := 0; page < 100; page++ {

---

任何未成功的调用——无论是信封中携带了错误,还是 HTTP 状态非 2xx——都会返回 `*ErrorResponse`。它带有 `Code`、`Message` 与 `RequestID` 字段,排障时把 `RequestID` 提供给支持团队即可定位。
Flashduty API 返回的未成功调用——无论是信封中携带了错误,还是 HTTP 状态非 2xx——都会返回 `*ErrorResponse`。它带有 `Code`、`Message` 与 `RequestID` 字段,排障时把 `RequestID` 提供给支持团队即可定位。

当 API 返回 429 时,错误被提升为 `*RateLimitError`：它内嵌 `*ErrorResponse`（所以 `errors.As` 取 `*ErrorResponse` 仍然成立),并额外带上 `RetryAfter` 提示。

<Note>
如果你收到的是带非 JSON 响应体的非 2xx 响应,SDK 会返回普通 `error`,而不是 `*ErrorResponse`。这表示响应来自网关、负载均衡器或代理等中间层,通常是请求超过了中间层超时。你可以重试请求,或将耗时较长的批量请求拆分为更小的批次；不要假定 `errors.As(err, &apiErr)` 能匹配此类错误。
</Note>

```go
_, _, err := client.Incidents.Info(ctx, &flashduty.IncidentInfoRequest{
IncidentID: "does-not-exist",
Expand Down