API errors

Zonos GraphQL API가 반환하는 error를 이해하고 해결합니다.

GraphQL

Zonos API는 두 가지 유형의 error를 반환합니다. transport 수준 failure용 HTTP status code와 application 수준 issue용 GraphQL error입니다. 대부분의 error는 extensions 필드에 classification이 포함되어 원인과 적절한 해결 방법을 파악하는 데 도움이 됩니다.

HTTP status codes

HTTP error는 transport 수준에서 request를 처리할 수 없을 때 반환됩니다.

Status code↕	Meaning↕
400	Invalid argument / bad request — request에 invalid input이 포함되어 있습니다.
401	Unauthorized — valid credential이 제공되지 않았습니다.
404	Not found — 요청한 resource가 존재하지 않습니다.
409	Resource conflict — request가 resource의 현재 state와 충돌합니다.
412	Failed precondition — 처리 전에 필요한 조건이 충족되지 않았습니다.
422	Unprocessable entity — request body는 구조적으로 valid하지만 invalid value가 포함되어 있습니다.
429	Rate limited — 짧은 기간에 request가 너무 많습니다. exponential backoff 후 retry하세요.
500	Internal server error — 예상치 못한 server-side failure가 발생했습니다. retry하세요. 지속되면 support에 문의하세요.
503	Service unavailable — service가 일시적으로 offline입니다. 잠시 후 retry하세요.
504	Timeout — server가 시간 내에 response를 받지 못했습니다. request를 retry하세요.

GraphQL error format

Application 수준 error는 response body의 errors 필드에 list로 반환됩니다. 각 error에는 message, 실패한 operation의 path, error type과 request ID가 포함된 extensions object가 있습니다.

1{

2 "errors": [

3 {

4 "message": "Description of the error",

5 "path": [

6 "landedCostCalculate"

7 ],

8 "extensions": {

9 "errorType": "BAD_REQUEST",

10 "requestId": "req_abc123"

11 }

12 }

13 ]

14}

Error classifications

extensions.errorType 필드는 error category와 권장 action을 나타냅니다.

Classification↕	HTTP equivalent↕	Meaning↕	Action↕
`BAD_REQUEST`	400	Invalid input 또는 request parameter.	request를 수정하세요 — required field, format, value를 확인하세요.
`NOT_FOUND`	404	참조한 resource가 존재하지 않습니다.	ID, code, required default 설정을 확인하세요.
`UNAVAILABLE`	503	요청한 service 또는 option이 이 route에서 사용할 수 없습니다.	다른 method, service level, destination을 시도하세요.
`PERMISSION_DENIED`	401 / 403	Authentication 또는 authorization failure.	credential과 account permission을 확인하세요.
`FAILED_PRECONDITION`	412	Required configuration 또는 setup 조건이 충족되지 않았습니다.	org settings를 확인하거나 support에 문의하세요.
`INTERNAL`	500	예상치 못한 server-side failure가 발생했습니다.	request를 retry하세요. issue가 지속되면 support에 문의하세요.
`UNKNOWN`	500	추가 classification 없이 예상치 못한 error가 발생했습니다.	request format을 확인하세요. issue가 지속되면 support에 문의하세요.

데모 예약하기

API errors

HTTP status codes

GraphQL error format

Error classifications

이 페이지가 도움이 되었나요?