오류
모든 실패는 예외를 던집니다. 클래스는 두 가지이며, 모든 API 오류에는 요청 id가 담깁니다.
오류 잡기
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}발송에서 나는 permission_error는 대개 워크스페이스가 아니라 키 자체의 발송 범위, 즉 키에 부여되지 않은 도메인이나 주소 때문입니다. 예제가 이 키로 어떤 주소에서 보낼 수 있는지를 addresses.list()로 확인해 출력하는 이유가 여기에 있습니다.
클래스
| 클래스 | 발생 시점 |
|---|---|
| `OpenEmailApiError` | API가 응답했지만 성공이 아니었습니다. status, type, code, param, docUrl, requestId, retryAfterSeconds를 담고 있습니다. |
| `OpenEmailNetworkError` | 응답이 전혀 오지 않았습니다. DNS, TLS, 끊긴 연결, 타임아웃, 또는 직접 넘긴 AbortSignal 때문입니다. cause를 담으며, 타임아웃이 원인이면 isTimeout이 true입니다. |
| `Error` | 아무것도 전송되기 전에 던져집니다. 키가 없거나 형식이 잘못된 경우, 사용할 수 없는 baseUrl, 브라우저 환경, 빈 id가 여기에 해당합니다. |
| 게터 | true가 되는 조건 |
|---|---|
| `isAuth` | type이 authentication_error인 401입니다. 키가 없거나, 자격 증명의 종류가 잘못되었거나, OpenEmail이 발급하지 않은 키입니다. |
| `isPermission` | permission_error, 즉 403입니다. 유효한 키이지만 필요한 스코프나 From 주소를 갖고 있지 않습니다. |
| `isScopeMissing` | code가 insufficient_scope인 경우로, 빠진 스코프를 명시하는 403입니다. |
| `isInvalidRequest` | invalid_request_error, 즉 400입니다. 해석할 수 없는 요청입니다. 크기 상한을 넘은 메시지는 422 message_too_large로 돌아오므로, 그 경우를 잡는 게터는 isValidation입니다. |
| `isValidation` | validation_error, 즉 422입니다. 스키마가 요청을 거부했으며 param이 해당 필드를 가리킵니다. |
| `isNotFound` | not_found_error, 즉 404입니다. 그런 리소스가 없습니다. |
| `isConflict` | conflict_error, 즉 409입니다. 리소스가 이미 이 작업을 할 수 있는 시점을 지났습니다. |
| `isRateLimited` | rate_limit_error, 즉 429입니다. 서버가 대기 시간을 지정한 경우 retryAfterSeconds에 그 값이 담깁니다. |
| `isServerError` | status가 500 이상입니다. 지원팀에 문의할 때는 requestId를 함께 알려 주십시오. |
| `isRetryable` | status가 408, 429, 500, 502, 503, 504 중 하나입니다. |
게터는 오류 봉투에서 고정된 쪽인 type을 읽습니다. code는 API가 개방적이고 추가만 된다고 보장하는 값이므로 string으로 남아 있으며, 알아보지 못하는 값은 그 type으로 취급하십시오. 닫힌 유니온으로 만들면 새로운 실패 모드를 읽는 대가로 SDK를 업그레이드해야 합니다.
API의 오류 봉투 형식이 아닌 본문도 여전히 OpenEmailApiError가 되며, type은 상태 코드에서 추론하고 code는 unrecognised_response로 설정됩니다. 본문이 JSON이 아닌 성공 응답도 마찬가지로 이 오류를 던집니다.
중단(abort) 역시 OpenEmailNetworkError이며, 요청 도중에 발생하든 재시도 전 대기 중에 발생하든 마찬가지입니다. 중단 사유는 cause에 보관됩니다. 직접 건 취소와 네트워크 실패를 구분해야 한다면 signal.aborted를 확인하십시오.
requestId
모든 OpenEmailApiError는 서버가 보낸 요청 id를 오류 본문이나 x-request-id 헤더에서 가져와 담고 있으며, 이 값만이 여러분의 실패를 서버 로그의 한 줄과 이어 줍니다. 성공은 파싱된 본문만으로 resolve되므로 거기서 읽을 요청 id는 없습니다.