Lỗi
Một cấu trúc, hai cấp độ, và id yêu cầu trên mọi phản hồi.
Cấu trúc bao
type là một tập cố định mà bạn có thể rẽ nhánh theo và sẽ không bao giờ mở rộng thêm. code cụ thể hơn và có thể được bổ sung, nên hãy xử lý một mã bạn không nhận ra theo type của nó. requestId có trên mọi phản hồi, kể cả phản hồi thành công, và là thứ liên kết một báo cáo với một dòng nhật ký.
{ "error": { "type": "validation_error", "code": "invalid_email_address", "message": "Not a valid email address: ada@", "param": "to.0", "docUrl": "https://openemail.uk/docs/api/errors#invalid_email_address", "requestId": "req_e103790543af4…" }}param dùng dấu chấm và chỉ số, nên nó trỏ tới đúng phần tử (to.0, attachments.2.filename) thay vì trường chứa phần tử đó.
Mã trạng thái
| Trạng thái | type | Các mã thường gặp |
|---|---|---|
| 400 | invalid_request_error | malformed_json, invalid_idempotency_key |
| 401 | authentication_error | missing_api_key, invalid_api_key, revoked_api_key, invalid_credential_type |
| 403 | permission_error | insufficient_scope, from_address_forbidden |
| 404 | not_found_error | resource_not_found |
| 409 | conflict_error | email_not_cancellable, translation_not_configured |
| 422 | validation_error | invalid_email_address, reserved_header, too_many_recipients, unknown_parameter, idempotency_key_reuse, label_not_directly_settable, unknown_language, translation_too_long |
| 429 | rate_limit_error | send_quota_exceeded, too_many_inboxes |
| 500 | api_error | internal_error |
| 503 | api_error | translation_failed |
Mã 404 không bao giờ phân biệt “không tồn tại” với “thuộc về không gian làm việc khác”. Điều đó là có chủ đích: bản thân sự khác biệt đó đã là thông tin.
Mã 429 không bao giờ kèm Retry-After, vì vậy hãy tự chọn thời gian chờ. send_quota_exceeded là hạn mức gửi hằng tháng và được đặt lại vào ngày đầu tiên của tháng, nên hãy hiển thị nó cho người dùng thay vì chờ rồi thử lại. too_many_inboxes là giới hạn tạo hộp thư dùng một lần, và gia hạn một hộp thư bạn đã có không tính vào giới hạn đó.
500 và 503 dùng chung một type nhưng có ý nghĩa khác nhau với bên gọi. 503 là một phụ thuộc không phản hồi (hiện tại đó là dịch vụ dịch), và yêu cầu đáng để thử lại nguyên vẹn; 500 là lỗi của chúng tôi và nên được báo cáo kèm requestId.
Xử lý lỗi
Rẽ nhánh theo type để quyết định hành vi và đọc code để lấy thông báo hiển thị cho người dùng. Một code không nhận ra không phải là lỗi trong client của bạn. Nó có nghĩa là chúng tôi đã đặt tên cho một lỗi chính xác hơn trước.
const res = await fetch(`${BASE}/emails`, { method: 'POST', headers, body }); if (!res.ok) { const { error } = await res.json(); switch (error.type) { case 'rate_limit_error': throw new RateLimited(error.code); case 'validation_error': // error.param points at the offending field throw new BadRequest(`${error.param}: ${error.message}`); case 'authentication_error': // revoked_api_key and expired_api_key are worth telling an operator apart throw new AuthFailed(error.code); default: // quote requestId when you report it throw new Unexpected(error.message, error.requestId); }}