Lỗi
Mọi thất bại đều ném ra lỗi. Hai lớp lỗi, và một request id trên mọi lỗi API.
Bắt một lỗi
import { OpenEmailApiError, OpenEmailNetworkError, openemail } from '@openemail/sdk' try { await openemail.emails.send(message)} catch (error) { if (error instanceof OpenEmailApiError) { if (error.isValidation) console.error(error.code, error.param, error.message) if (error.isPermission) console.error(await openemail.addresses.list()) if (error.isRateLimited) console.error('try again in', error.retryAfterSeconds, 'seconds') console.error(error.status, error.requestId) } if (error instanceof OpenEmailNetworkError && error.isTimeout) console.error('no answer in time') throw error}Một permission_error khi gửi thường là do phạm vi gửi của KHOÁ, một tên miền hoặc một địa chỉ mà nó không được cấp, chứ không phải do workspace, và đó là lý do ví dụ này in ra những gì addresses.list() cho biết khoá này được phép gửi dưới danh nghĩa nào.
Các lớp lỗi
| Lớp | Khi nào |
|---|---|
| `OpenEmailApiError` | API đã trả lời, và không phải bằng một phản hồi thành công. Mang theo status, type, code, param, docUrl, requestId và retryAfterSeconds. |
| `OpenEmailNetworkError` | Không có phản hồi nào tới: DNS, TLS, một kết nối bị rớt, hết thời gian chờ, hoặc chính AbortSignal của bạn. Mang theo cause, và isTimeout là true khi nguyên nhân là hết thời gian chờ. |
| `Error` | Được ném ra trước khi bất cứ thứ gì được gửi: một khoá thiếu hoặc sai định dạng, một baseUrl không dùng được, một trình duyệt, một id rỗng. |
| Getter | True khi |
|---|---|
| `isAuth` | type là authentication_error, một 401: không có khoá, sai loại thông tin xác thực, hoặc một khoá không do chúng tôi cấp. |
| `isPermission` | permission_error, một 403: một khoá hợp lệ nhưng thiếu scope hoặc thiếu địa chỉ From mà nó cần. |
| `isScopeMissing` | code là insufficient_scope, tức 403 có nêu tên scope còn thiếu. |
| `isInvalidRequest` | invalid_request_error, một 400: một yêu cầu không thể hiểu được. Một thông điệp vượt trần kích thước trả về 422 message_too_large, nên isValidation mới là getter bắt được nó. |
| `isValidation` | validation_error, một 422: schema đã từ chối nó, và param nêu tên trường. |
| `isNotFound` | not_found_error, một 404: không có tài nguyên như vậy. |
| `isConflict` | conflict_error, một 409: tài nguyên đã qua thời điểm còn có thể làm điều này với nó. |
| `isRateLimited` | rate_limit_error, một 429. retryAfterSeconds giữ thời gian chờ khi máy chủ có nêu ra. |
| `isServerError` | status từ 500 trở lên. Hãy trích requestId nếu bạn liên hệ bộ phận hỗ trợ. |
| `isRetryable` | status là 408, 429, 500, 502, 503 hoặc 504. |
Các getter đọc type, nửa đã đóng băng của phong bì lỗi. code vẫn là một string, vì API đảm bảo nó là tập mở và chỉ bổ sung thêm, nên hãy xử lý một mã bạn không nhận ra theo type của nó. Một union đóng sẽ biến việc nâng cấp SDK thành cái giá phải trả để đọc được một kiểu lỗi mới.
Một body không phải phong bì lỗi của API vẫn trở thành một OpenEmailApiError, với type suy ra từ status và code đặt thành unrecognised_response. Một phản hồi thành công mà body không phải JSON cũng ném ra lỗi đó.
Một lần huỷ (abort) cũng là một OpenEmailNetworkError, dù nó xảy ra trong lúc gửi yêu cầu hay trong lúc chờ trước một lần thử lại, và lần huỷ đó được giữ trên cause. Hãy kiểm tra signal.aborted khi bạn cần phân biệt việc tự mình huỷ với một sự cố mạng.
requestId
Mọi OpenEmailApiError đều mang theo request id mà máy chủ đã gửi, lấy từ body lỗi hoặc từ header x-request-id, và đó là thứ duy nhất nối sự cố của bạn với một dòng trong log của máy chủ. Một phản hồi thành công chỉ trả về body đã phân tích, nên ở đó không có request id để đọc.