code는 안정적이므로 이것으로 분기하세요. message는 사람이 읽는 용도이고 바뀔 수 있습니다. details는 덧붙일 정보가 있을 때 포함됩니다. 검증 오류라면 대개 { field, message } 배열이고, { "id": "..." }나 { "retryAfterSec": 5, "retryable": true } 같은 객체일 수도 있습니다.
접수된 뒤 나중에 실패한 태스크는 HTTP 오류를 만들지 않습니다. 대신 태스크 실패 코드로 알립니다.
요청 오류 코드
상태 코드보다
error.code로 분기하세요. VALIDATION_ERROR는 400과 422로 모두 나타납니다. 429는 내 한도에 닿았다는 뜻이고, 503은 서버 용량이 잠시 모자라다는 뜻입니다.
Retry-After
POST /v1/async/task, POST /v1/async/task/batch, POST /v1/async/task/grid의 모든 429와 503에는 Retry-After 헤더(초)가 붙습니다. 이 코드들 대부분은 details.retryAfterSec와 details.retryable: true도 담습니다. 엣지 요청 한도에서 나온 429에는 둘 다 없습니다. 크레딧과 한도를 참고하세요.
페이로드 크기 한도
지역 거부
REGION_UNSUPPORTED는 태스크를 큐에 넣기 전에 결정되므로, 태스크가 실패하기를 기다리지 않고 즉시 알 수 있습니다.
배치와 그리드의 항목별 오류
POST /v1/async/task/batch에서 형식이 올바른 요청은 항목이 실패해도 200을 반환합니다. 상태는 요청을, results[].success는 각 태스크를 설명하며, 실패한 항목에는 요청 오류와 같은 { code, message, details, timestamp } 객체가 담깁니다.
QUEUE_BACKPRESSURE, SERVER_OVERLOADED로 실패한 항목은 대기 시간을 details.retryAfterSec에 담습니다. 요청 자체가 400, 413, 429, 503으로 실패하는 것은 배치 전체가 거부될 때뿐입니다.
POST /v1/async/task/grid는 거부된 지점을 같은 방식으로 points[]에 보고합니다. POST /v1/batches는 항목 하나라도 잘못되면 배치 전체를 400으로 거부하고, 접수에서 거절된 항목(INSUFFICIENT_CREDITS 등)은 REJECTED로 저장합니다. idempotencyKey가 배치보다 먼저 만들어진 태스크와 일치했던 항목은 그 태스크의 보존 기간이 끝나면 TASK_NOT_RETAINED가 담긴 FAILED로 표시됩니다. 배치와 그리드를 참고하세요.
태스크 실패 코드
큐에 들어간 뒤 실패한 태스크는FAILED로 끝납니다. 폴링은 요청 오류 객체가 아니라 최상위 error 문자열을 반환합니다.
response.error에 담습니다. 문자열은 코드로 시작하므로 코드로 분기하세요.