# 오류

> 오류 형식과 코드별 대처 방법.

Source: https://piqline.com/ko/docs/api/errors

모든 API 오류는 RFC 9457 형식의 `application/problem+json` 응답입니다.

```json
{
  "type": "https://piqline.com/docs/api/errors#insufficient_scope",
  "title": "Scope insuffisant",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "searchWeb demande le scope explore.",
  "request_id": "8c0c051b-c3e6-4fa0-8b98-0aa227cf3c2a",
  "missing_scopes": ["explore"]
}
```

| 필드 | 의미 |
| --- | --- |
| `type` | 이 페이지에서 해당 오류를 설명하는 섹션의 URL |
| `title` | 프랑스어로 된 짧은 제목 |
| `status` | HTTP 상태 |
| `code` | 오류의 고정 식별자. 이 값으로 판별하십시오 |
| `detail` | 프랑스어로 된 읽을 수 있는 설명이며, 버전에 따라 바뀔 수 있습니다 |
| `request_id` | 요청 ID. `X-Request-Id` 헤더에도 들어 있습니다 |

오류에 따라 `missing_scopes`, `issues` 같은 다른 필드가 추가됩니다.

문의할 때는 `request_id`를 함께 알려 주십시오. 로그에서 요청을 찾을 수 있으며, 키가 유효했다면 설정 → API 및 MCP의 기록에서도 찾을 수 있습니다. 문의 양식은 [문의 페이지](/contact)에 있습니다.

## 코드

### `missing_key`

**401** · API 키 없음

**원인.** 요청에 키가 없습니다.

**대처 방법.** `Authorization: Bearer piq_live_…`(또는 `x-api-key`)를 보내십시오.

### `invalid_key`

**401** · 유효하지 않은 API 키

**원인.** 키의 형식이 잘못되었거나(잘렸거나 다시 입력한 사본), 알 수 없거나, 폐기되었거나, 만료되었거나, 키를 만든 사람이 워크스페이스를 떠났습니다. `detail`에서 형식 문제인지 상태 문제인지 알 수 있습니다.

**대처 방법.** 복사한 키를 확인하십시오. 키가 폐기되었거나 만료되었다면 설정 → API 및 MCP에서 새 키를 만드십시오.

### `insufficient_scope`

**403** · 스코프 부족

**원인.** 라우트 또는 도구가 요구하는 스코프가 키에 없습니다. `missing_scopes`에 해당 스코프가 나열됩니다.

**대처 방법.** 해당 스코프가 있는 키를 만드십시오. 기존 키의 스코프는 변경할 수 없습니다.

### `forbidden`

**403** · 접근 금지

**원인.** 키를 만든 사람의 역할로는 이 도구 또는 에이전트에 접근할 수 없습니다.

**대처 방법.** 필요한 역할이 있는 계정으로 키를 만드십시오(쓰기 및 실행 도구와 온보딩 에이전트는 소유자 또는 관리자).

### `not_found`

**404** · 찾을 수 없음

**원인.** 알 수 없는 라우트, 도구 또는 에이전트입니다. 채팅의 대화형 카드(`askUser`, `proposeSources`, `proposeBoard` 등)는 호출할 수 있는 도구가 아닙니다.

**대처 방법.** `GET /api/v1/tools`와 `GET /api/v1/agents`로 유효한 이름을 확인하십시오.

### `invalid_input`

**422** · 잘못된 입력

**원인.** 본문이 유효한 JSON이 아니거나 입력이 도구의 스키마와 맞지 않습니다. `issues`가 잘못된 각 필드(`path`, `message`)를 가리킵니다.

**대처 방법.** 본문을 도구의 `input_schema`와 비교하십시오(`GET /api/v1/tools/{nom}`).

### `tool_error`

**422** · 도구 오류

**원인.** 도구가 사용자의 데이터와 관련된 이유로 요청을 거부했습니다. 예를 들어 이 워크스페이스에 없는 항목입니다. `detail`에 이유가 나와 있습니다.

**대처 방법.** `detail`에 따라 입력을 수정하십시오. 아무것도 바뀌지 않으면 같은 호출은 같은 응답을 받습니다.

### `rate_limited`

**429** · 요청이 너무 많음

**원인.** 키가 분당 한도를 초과했습니다.

**대처 방법.** `Retry-After` 헤더에 표시된 초만큼 기다린 후 다시 시도하십시오. 호출 간격을 두십시오.

### `quota_exceeded`

**429** · 일일 쿼터 도달

**원인.** 키가 일일 요청 한도에 도달했습니다. 카운터는 매일 UTC 자정에 초기화됩니다.

**대처 방법.** UTC 자정 이후에 다시 시도하십시오. 한도를 높이려면 [문의 페이지](/contact)로 문의하십시오.

### `budget_exhausted`

**402** · 월간 크레딧 소진

**원인.** 키의 워크스페이스가 월간 크레딧 한도에 도달했습니다. 비용이 드는 모든 작업(에이전트, 유료 도구, 수집)은 호출 전에 거부되며, 진행 중인 에이전트 턴은 한도에 도달하면 중단됩니다. `detail`에 재개 날짜가 나와 있습니다.

**대처 방법.** `detail`에 표시된 재개 날짜까지 기다리거나, 워크스페이스 소유자에게 한도를 높여 달라고 요청하십시오.

### `plan_restricted`

**403** · 플랜에 포함되지 않음

**원인.** 키의 워크스페이스 플랜이 이 요청을 허용하지 않습니다. API를 열어 주지 않거나, 읽기 전용으로만 열어 주는데 요청이 쓰기, 구독, 조사 또는 에이전트 시작을 수행합니다. `plan`에 플랜이, `api_access`에 접근 수준(`none`, `read`)이 표시됩니다.

**대처 방법.** 필요한 접근을 열어 주는 플랜을 Piqline에 요청하십시오. 읽기에는 Équipe, 전체 접근에는 Business가 필요합니다.

### `unavailable`

**503** · 서비스 이용 불가

**원인.** 요청이 의존하는 서비스(키 확인, 에이전트 모델 또는 공급자)가 응답하지 않습니다.

**대처 방법.** 대기 시간을 늘려 가며 다시 시도하십시오. 오류가 계속되면 문의할 때 `request_id`를 알려 주십시오.

### `not_configured`

**503** · 구성되지 않음

**원인.** 서버에 API가 구성되어 있지 않습니다. 환경 변수가 없습니다.

**대처 방법.** 문의할 때 `request_id`를 알려 주십시오. 이 경우는 Piqline만 해결할 수 있습니다.

### `internal`

**500** · 내부 오류

**원인.** Piqline 쪽에서 예기치 않은 오류가 발생했습니다. `detail`은 의도적으로 모호하게 표시됩니다.

**대처 방법.** 다시 시도하십시오. 오류가 계속되면 문의할 때 `request_id`를 알려 주십시오.
