Guides / Errors
오류 코드
오류는 HTTP 상태 코드와 JSON 본문의 error.code로 알려 줍니다. 분기는 code로 하세요. message는 사람이 읽는 영어 문장이고 바뀔 수 있습니다. 이 페이지의 표가 코드마다 한국어 설명을 줍니다.
응답 형식
http
HTTP/2 403
content-type: application/json
{
"error": {
"code": "PLAN_REQUIRED",
"message": "This endpoint requires the Enterprise plan. Contact: help@alpsoft.io",
"docs": "https://openapi.chickstockfi.com/docs"
}
}code: 아래 표의 대문자 코드. 프로그램 분기에 씁니다.message: 원인과 할 일을 적은 영어 문장. 로그에 남기고, 사용자 화면에는 code에 맞춘 내 문구를 보여 주세요.docs: 관련 문서 주소. 응답에 따라 없을 수 있습니다.
쿼리 파라미터 검사(예: limit 범위)를 통과하지 못하면 400 BAD_REQUEST를 같은 모양으로 돌려주고, message에 어느 칸이 왜 틀렸는지 적습니다.
본문 없는 400
인코딩하지 않은 한국어 같은 비ASCII 쿼리 값은 API에 닿기 전에 엣지에서 본문 없는 400으로 거절될 수 있습니다. 이 응답에는
error가 없습니다. 쿼리 값은 curl -G --data-urlencode "account=매출액"처럼 인코딩해 보내거나, 영문 코드(account=revenue, period=FY2025)를 쓰세요.Data API 코드
| 상태 | 코드 | 뜻 | 할 일 |
|---|---|---|---|
| 400 | BAD_SYMBOL | 종목 코드 형식이 맞지 않습니다 | 국내는 6자리 코드(예: 005930)를 씁니다. 뉴스는 영숫자 1~12자 티커도 받습니다. 삼성전자 · 005930 |
| 400 | BAD_ID | 접수번호·기사 ID 형식이 맞지 않습니다 | 공시는 14자리 접수번호, 기사는 응답의 id를 그대로 씁니다. |
| 400 | BAD_QUERY | 검색어가 없습니다 | 검색 엔드포인트에 q를 넣습니다. |
| 400 | BAD_DATE | 날짜 형식이 틀렸거나 존재하지 않는 날짜입니다 | YYYY-MM-DD 형식의 실제 달력 날짜를 보내세요. message에서 잘못된 파라미터를 확인합니다. |
| 400 | BAD_PERIOD | period 형식이 맞지 않습니다 | 재무제표는 FY2025 · 2026Q3 · 2025H1 · latest_quarter, 컨센서스·가이던스는 2026Q3 · FY2026 · last · next를 씁니다. message에 받는 꼴이 적혀 있습니다. |
| 400 | BAD_REQUEST | 필수 조건이 빠졌습니다 | 예: /clinical-trials는 symbol 또는 sponsor가 필요합니다. |
| 400 | UNSUPPORTED_MARKET | 지원하지 않는 시장의 종목입니다 | 브리핑은 코스피·코스닥 종목과 ETF만 지원합니다. |
| 400 | BAD_CURSOR | cursor 형식이 틀렸거나 다른 필터에서 나왔습니다 | 앞 응답의 next_cursor를 같은 필터로 그대로 보냅니다. 필터를 바꾸면 cursor 없이 처음부터 부릅니다. |
| 400 | MARKET_NOT_AVAILABLE | 준비 중인 시장입니다(일본·중국) | 지금은 한국(KR)·미국(US) 데이터만 제공합니다. |
| 401 | UNAUTHORIZED | 키가 없거나 Data API 키 형식(ck_live_)이 아닙니다 | 헤더를 확인합니다. PRO API 키는 Data API에서 쓸 수 없습니다. |
| 401 | INVALID_KEY | 없는 키이거나 폐기된 키입니다 | 콘솔에서 활성 키를 확인하고 필요하면 새로 발급합니다. |
| 401 | KEY_EXPIRED | API 문서 세션 키(ck_docs_)가 만료됐습니다 | 로그인한 채 API 문서에서 새로 받거나 내 키를 씁니다. 문서 세션 키는 최대 60분입니다. |
| 403 | PLAN_REQUIRED | 유료 등급(Launch · Business · Scale · Enterprise)이나 PoC가 필요한 엔드포인트입니다 | 무료 체험 키이거나 유료 등급 기간이 끝나 Free로 바뀐 계정입니다. 계약 상태를 확인하거나 도입 문의를 남기세요. |
| 403 | MARKET_NOT_ENTITLED | 계약하지 않은 시장의 데이터입니다 | GET /key의 markets로 계약 범위를 확인합니다. 범위 추가는 help@alpsoft.io로 문의하세요. 이 요청은 한도에 세지 않습니다. |
| 403 | POC_ENDED | PoC 기간이 끝나 계정이 멈췄습니다 | 모든 키가 같은 응답을 받습니다. 기간 연장이나 정식 계약은 help@alpsoft.io로 문의하세요. 연장되면 같은 키로 다시 열립니다. |
| 403 | READ_ONLY_KEY | API 문서 세션 키로 GET 밖의 요청을 보냈습니다 | 문서 세션 키는 GET 엔드포인트만 부릅니다. POST /query 등은 내 키로 보냅니다. |
| 403 | FEATURE_DISABLED | 제공을 중단한 엔드포인트입니다 | 기존 계약 키에만 열려 있습니다. 대체 엔드포인트는 레퍼런스의 설명을 봅니다. |
| 404 | SYMBOL_NOT_FOUND | Phoenix AI가 모르는 종목입니다 | 형식은 맞지만 상장 종목이 아닙니다. 코드·티커를 확인하세요. 종목은 있는데 자료가 없으면 NOT_FOUND입니다. |
| 404 | NOT_APPLICABLE | 이 증권 유형에는 해당하지 않는 데이터입니다 | ETF·ETN 같은 펀드형 상품은 재무제표·지표·컨센서스 등 회사 데이터가 없습니다. 뉴스·공시는 그대로 부를 수 있습니다. |
| 404 | NOT_FOUND | 종목은 있지만 요청한 데이터(계정·기간 등)가 없습니다 | 코드·ID를 확인합니다. 같은 요청을 반복하지 마세요. |
| 404 | NO_HISTORY | 그 날짜에 저장된 브리핑이 없습니다 | 과거 날짜는 저장본만 제공합니다. date를 비우면 당일 브리핑을 받습니다. |
| 429 | RATE_LIMITED | 분당 한도를 넘었습니다 | Retry-After 초만큼 기다린 뒤 다시 보냅니다. |
| 429 | QUOTA_EXCEEDED | 하루 한도를 다 썼습니다 | 한국시간 0시 이후 다시 시도합니다. |
| 429 | AI_QUOTA_EXCEEDED | 등급별 하루 AI 호출 한도를 다 썼습니다 | Retry-After(한국시간 0시까지) 뒤에 다시 시도합니다. 일반 데이터 호출은 그대로 됩니다. |
| 429 | AI_MONTHLY_QUOTA_EXCEEDED | 계약한 AI 호출 월 한도를 다 썼습니다 | Retry-After(다음 주기 또는 플랜 종료까지) 뒤에 다시 시도합니다. 일반 데이터 호출은 그대로 됩니다. |
| 500 | INTERNAL | 서버 오류입니다 | 잠시 뒤 다시 시도합니다. 계속되면 문의해 주세요. |
| 503 | UNAVAILABLE | 일시적으로 처리할 수 없습니다 | 잠시 뒤 백오프로 다시 시도합니다. |
PRO API 코드
| 상태 | 코드 | 뜻 | 할 일 |
|---|---|---|---|
| 400 | BAD_REQUEST · BAD_SYMBOL | 파라미터·종목 코드 형식 오류 | 레퍼런스의 형식을 확인합니다(공시 접수번호 14자리, 국내 6자리 코드 또는 미국 티커). |
| 401 | UNAUTHORIZED | 키가 없거나 PRO API 키 형식(ck_pers_)이 아닙니다 | 헤더를 확인합니다. |
| 401 | WRONG_KEY_SCOPE | Data API 키(ck_live_)나 API 문서 세션 키(ck_docs_)로 PRO API를 불렀습니다 | 콘솔에서 PRO API 키를 발급해 씁니다. MCP는 Data API 키로도 연결되며 그때는 Data API 도구만 나옵니다. 오류의 docs는 MCP 연결 안내(/docs/mcp)를 가리킵니다. |
| 401 | INVALID_KEY | 없는 키이거나 폐기된 키입니다 | 활성 키를 확인합니다. |
| 402 | BUDGET_EXCEEDED | 이번 달 AI 비용 상한에 닿았습니다 | 저장된 요약 조회는 계속 됩니다. 다음 달에 다시 열리며, 상향은 문의하세요. |
| 403 | PLAN_REQUIRED | 계정에 PRO 플랜이 없습니다 | 계정에 PRO 플랜이 적용된 뒤 다시 시도합니다. |
| 403 | PLAN_EXPIRED | 플랜 기간이 끝났습니다 | 플랜을 연장합니다. |
| 403 | PLAN_NOT_STARTED | 플랜 시작일 전입니다 | message의 시작 시각 이후에 호출합니다. |
| 403 | PLAN_INACTIVE | 플랜이 정지 또는 해지됐습니다 | 문의하세요. |
| 400 · 403 | MARKET_NOT_AVAILABLE · MARKET_NOT_ENTITLED | 준비 중인 시장(일본·중국) · 계약하지 않은 시장 | /me의 markets로 계약 범위를 확인합니다. MCP 도구는 같은 코드의 도구 오류로 답합니다. |
| 403 | POC_ENDED | PoC 기간이 끝난 계정입니다 | PRO API 플랜이 남아 있어도 멈춥니다. 기간 연장이나 정식 계약을 문의하세요. |
| 403 | PRODUCT_REQUIRED | 이 엔드포인트에 필요한 상품(Data 또는 Ask)이 플랜에 없습니다 | Bundle 또는 해당 상품으로 바꿉니다. |
| 403 | PRO_ACCESS_REQUIRED | 대화형 질문 권한이 없는 계정입니다 | 문의하세요. |
| 404 | NOT_FOUND | 데이터를 찾지 못했습니다 | 코드·접수번호를 확인합니다. |
| 409 | ASK_IN_PROGRESS | 이미 처리 중인 질문이 있습니다(계정당 동시 1건) | 진행 중인 job_id의 결과를 받은 뒤 새로 묻습니다. |
| 429 | RATE_LIMITED | 초당 한도를 넘었습니다 | Retry-After 초만큼 기다립니다. |
| 429 | DAILY_QUOTA_EXCEEDED | 하루 호출 한도를 다 썼습니다 | 한국시간 0시에 다시 열립니다(Retry-After 포함). |
| 429 | SUMMARY_DAILY_LIMIT | 오늘 AI 공시 요약 생성 한도를 다 썼습니다 | 저장된 요약은 계속 조회됩니다(generate=false). |
| 429 | ASK_DAILY_LIMIT | 오늘 질문 한도를 다 썼습니다(웹 PRO 포함) | 한국시간 0시 이후 다시 묻습니다. |
| 429 | AI_QUOTA_EXCEEDED | 계정의 하루 AI 호출 한도를 다 썼습니다 | 질문·요약 생성은 한국시간 0시에 다시 열립니다(Retry-After 포함). |
| 429 | AI_MONTHLY_QUOTA_EXCEEDED | 계정의 AI 호출 월 한도를 다 썼습니다 | 질문·요약 생성은 다음 주기(또는 플랜 종료)에 다시 열립니다(Retry-After 포함). |
| 503 | UNAVAILABLE | 일시적으로 처리할 수 없습니다 | 잠시 뒤 다시 시도합니다. |
MCP 도구 호출에서 한도에 걸리면 HTTP 오류 대신 도구 결과가 오류(isError)로 오고, 같은 코드가 들어 있습니다. 자세한 내용은 MCP 연결을 보세요.