가이드
오류
오류 형식과 코드별 대처 방법.
모든 API 오류는 RFC 9457 형식의 application/problem+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의 기록에서도 찾을 수 있습니다. 문의 양식은 문의 페이지에 있습니다.
코드#
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 자정 이후에 다시 시도하십시오. 한도를 높이려면 문의 페이지로 문의하십시오.
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를 알려 주십시오.