---
title: API 오류
description: 구조화된 오류 응답, 요청 ID, HTTP 상태 분류, 안정적인 코드, 재시도 범위를 처리합니다.
species: reference
---
# API 오류

모든 API 실패는 동일한 응답 구조를 사용합니다. 메시지 텍스트가 아닌 `error.code`를 기준으로 분기하세요.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Missing required parameter.",
    "param": "sql",
    "doc_url": "https://api.supernova.ai/docs#parameter_missing",
    "request_id": "req_..."
  }
}
```

`Request-Id` 응답 헤더에는 `request_id`와 같은 값이 포함됩니다. 지원팀에 문의할 때 이 값을 제공하세요. `param`은 입력 하나를 지정할 수 있을 때만 나타납니다.

## 상태 분류

| 상태 | 의미 | 재시도 방법 |
|---|---|---|
| `400` | 잘못된 입력 또는 거부된 기능 | 요청 변경 |
| `401` | 자격 증명 누락, 형식 오류, 만료 또는 폐기 | 자격 증명 갱신 또는 교체 |
| `403` | 인증되었으나 권한 범위 또는 역할 부족 | 적절한 접근 권한 요청 |
| `404` | 리소스가 없거나 이 조직에서 볼 수 없음 | 다른 테넌트에 존재하는지 추론하지 않기 |
| `409` | 현재 상태가 작업과 충돌 | 현재 상태를 읽은 뒤 결정 |
| `429` | 호출자, 조직 또는 동시 실행 한도 도달 | `Retry-After` 따르기 |
| `500` | 예기치 않은 서버 오류 | 멱등 요청이면 대기 시간을 늘리며 재시도 |
| `503` | 필요한 서비스 사용 불가 | 대기 시간을 늘리며 재시도 |

## 공통 코드

| 코드 | 의미 |
|---|---|
| `invalid_json` | 본문이 유효한 JSON이 아님 |
| `parameter_missing` | 필수 입력 누락 |
| `invalid_cursor` | 커서가 해당 컬렉션에서 발급되지 않음 |
| `invalid_format` | 요청한 표현 형식을 지원하지 않음 |
| `authentication_required` | bearer 자격 증명 누락 |
| `invalid_token` | 자격 증명 검증 실패 |
| `insufficient_scope` | 자격 증명에 엔드포인트의 권한 범위가 없음 |
| `rate_limited` | 요청 빈도 초과 |
| `idempotency_key_reused` | 키가 다른 입력에 연결되어 있음 |
| `query_not_found` | 이 조직에서 쿼리를 사용할 수 없음 |
| `job_not_found` | 이 조직에서 작업을 사용할 수 없음 |
| `catalog_not_found` | 스키마나 테이블이 없거나 숨겨져 있음 |
| `source_not_found` | 소스가 없거나 숨겨져 있음 |
| `send_not_found` | 전송 또는 해당 실행이 없거나 숨겨져 있음 |

리소스별 추가 코드는 해당 코드를 반환하는 작업 설명에 나와 있습니다.