# OpenAPI 청구 및 오류

플랫폼 잔액, 요청 및 결과 요금, 페이지 청구, 안전한 재시도를 이해합니다.

이 페이지는 `/api/v1/data/*`, 즉 Felo OpenAPI 플랫폼 전용 API에 적용됩니다. 호출은 USD로 표시되는 서비스 크레딧 잔액인 **플랫폼 잔액**을 사용합니다. Felo Pro 크레딧은 소모하지 않습니다. `/v2` 아래의 기존 [Felo API](https://openapi.felo.ai/ko/docs/api-reference/felo-apis.md)는 Pro 크레딧을 사용합니다.

## 현재 가격 읽기

```bash
curl -sS https://openapi.felo.ai/api/v1/data/prices
```

이 공개 엔드포인트는 키가 필요하지 않습니다. 항목을 작업 ID로 일치시키고 현재 요율과 청구 단위를 읽으세요. 모든 작업이 같은 비용이라고 가정하거나, 예시의 요율을 애플리케이션에 고정하지 마세요.

| 작업 ID | 청구 단위 |
|---|---|
| `web.search`, `web.read`, `chat` | 요청 |
| `x.user.info`, `x.user.search`, `x.user.tweets`, `x.tweet.search`, `x.tweet.replies` | 반환 결과 |
| `ppt.generate` | 생성된 페이지 |
| `ppt.export` | 내보내기 요청 |
| `ppt.generate.status`, `ppt.generate.historical`, `ppt.export.status`, `ppt.delete` | 새 요금 없음 |

무료 상태 조회가 기본 생성이나 내보내기를 무료로 만드는 것은 아닙니다. X의 경우 페이지네이션과 중첩 반환 레코드가 과금 대상 사용량을 늘릴 수 있습니다.

## 잔액과 예약

실행 전에 서비스는 작업에 충분한 잔액을 예약할 수 있습니다. 성공한 작업은 해당 예약분으로 정산되며, 확인된 실패는 예약을 해제합니다. 비동기 작업의 경우 ID를 반환했다고 해서 청구가 이미 최종 확정되었다는 뜻은 아닙니다.

PPT 페이지 가격은 생성 시 10페이지를 예약합니다. 성공적인 생성은 실제 출력을 정산하고 남은 자금을 해제합니다. 생성과 내보내기는 별도 요금입니다. 반복 내보내기 동작은 [PPT 워크플로](https://openapi.felo.ai/ko/docs/data-api/guides/felo-ppt.md)를 참조하세요.

실행 또는 정산이 불확실한 경우, 서비스가 조정하는 동안 예약이 보류 상태로 남을 수 있습니다. 모든 타임아웃이나 5xx를 작업이 없었다거나 반복 요청이 무료라는 증거로 간주하지 마세요.

[Console Billing](https://openapi.felo.ai/console/billing)에서 가용 잔액과 사용량을 검토하세요. 계정 수준 충전 안내는 [Billing and Credits](https://openapi.felo.ai/ko/docs/faq/billing-and-credits.md)를 참조하세요.

## API를 통해 지갑 사용량 조회하기

계정 소유자는 **Felo 로그인 토큰**을 사용하여 지갑 호출 기록을 확인할 수 있습니다. 이 자격 증명은 Data API 호출에 사용하는 API Key와 다릅니다. `FELO_API_KEY`를 대체하지 마세요.

```bash
curl -sS 'https://openapi.felo.ai/api/wallet/usage?call_type=data' \
  -H 'Authorization: Bearer YOUR_FELO_LOGIN_TOKEN'
```

기록은 `data.items` 아래에 있으며, `call_type=data`는 기능 호출을 필터링합니다. 사용량을 계정의 현재 가격과 비교하세요. 기록을 읽는다고 해서 또 다른 생성 작업이 제출되지는 않습니다. 계정 검토와 충전을 위해 Console Billing은 계속 사용할 수 있습니다.

## 오류를 방어적으로 읽기

먼저 HTTP 상태를 확인하세요. 오류는 아래 두 형태 중 하나를 사용할 수 있으며, 값은 예시입니다:

```json
{"error":{"code":"invalid_parameter","message":"Check the request fields"},"request_id":"example-request-id"}
```

```json
{"status":402,"code":"INSUFFICIENT_BALANCE","message":"Insufficient balance","request_id":"example-request-id"}
```

존재하면 `error.code` / `error.message`를 읽고, 그렇지 않으면 `code` / `message`를 읽으세요. 반환되면 `request_id`를 보존하세요. 성공 응답은 작업별로 다릅니다. 모두 같은 오류 또는 `data` 엔벨로프로 강제하지 마세요.

## 다음에 무엇을 할지 결정하기

| HTTP 상태 | 일반적인 원인 | 다음 단계 |
|---|---|---|
| 400 | 누락되었거나 잘못된 매개변수 | 재시도 전에 요청을 수정하세요 |
| 401 | 키 누락, 잘못됨, 폐기됨 또는 만료됨 | 키와 인증 헤더를 확인하세요 |
| 402 | 플랫폼 잔액 부족 | 가용 잔액과 보류 중인 예약을 확인하고 필요하면 충전하세요 |
| 404 | 이 계정에서 리소스를 찾을 수 없거나 접근할 수 없음 | ID와 생성 계정을 확인하세요 |
| 409 | 현재 작업 상태와 작업이 충돌하거나, 실행이 확인되지 않음 | 오류 코드를 읽고 기존 작업을 조회하세요. 즉시 중복 제출하지 마세요 |
| 410 | 리소스 만료 또는 삭제됨 | 저장된 파일을 사용하세요. 필요할 때만 새 작업을 만드세요 |
| 429 | 속도 제한 또는 API 키 할당량 초과 | 재설정 정보를 확인하고, 속도를 늦추거나 할당량 재설정을 기다리세요 |
| 502 / 503 / 504 | 상위 시스템, 가용성, 타임아웃 또는 정산 실패 | 유료 작업을 재시도하기 전에 작업이 이미 존재하는지 확인하세요 |

`execution_unconfirmed`(409)와 `billing_settlement_pending`(503)은 특별히 주의해야 합니다. 유료 작업을 즉시 재제출하지 마세요. 알려진 작업을 조회하거나 요청 ID와 함께 지원팀에 문의하세요. 성공적인 HTTP 상태와 빈 결과는 오류 응답과 다릅니다.

## 중복 작업 없이 재시도하기

- 읽기 전용 작업과 export-status 조회에는 제한된 백오프를 사용하고, `Retry-After`가 있으면 이를 따르세요.
- 저장된 `task_id`가 있는 실패한 생성 요청은 다른 작업을 만들기 전에 해당 작업을 조회하세요.
- ID를 받기 전에 연결이 실패했다면 결과를 알 수 없습니다. 다시 보내면 요청이 중복 제거될 것이라고 가정하지 마세요.
- 429의 경우 짧은 속도 제한과 API 키 할당량 창을 구분하세요. 반복 재시도로는 할당량을 재설정할 수 없습니다.
- 구성한 데드라인 이후에는 재시도를 중단하고 호출자에게 실행 가능한 오류를 보여주세요.

지원이 필요하면 엔드포인트, 대략적인 시간, HTTP 상태, 요청 ID를 제공하세요. 전체 API 키는 절대 포함하지 마세요.