Error handling

Every error uses the same format. Branch on code and use message only for human readers.

{
  "code": "PROMPT_SET_NOT_FOUND",
  "message": "프롬프트 세트를 찾을 수 없습니다"
}

Validation errors include a details array listing each field violation.

{
  "code": "COMMON_VALIDATION",
  "message": "데이터 검증에 실패했습니다",
  "details": [
    "models: 최소 1개 이상이어야 합니다",
    "keywords: 최대 100개까지 입력할 수 있습니다"
  ]
}

Error messages are returned in Korean (ko) or English (en) based on the Accept-Language header. If the header is missing or the language is not supported, messages are returned in English. The code value is always the same regardless of language.

HTTP status codes

Status	Meaning	What to do
`400`	Bad request (validation failure, invalid cursor, etc.)	Fix the request and retry. Retrying the same request has no effect
`401`	Authentication failed	Check the `API-Key` header and the key value
`402`	Insufficient credits (`INSUFFICIENT_CREDITS`)	Check your balance with `GET /credits/me` and top up. See Credits
`404`	Resource not found	Check that the ID belongs to a resource in your organization
`409`	State conflict (for example, more than 1,000 prompts per set)	Check the resource state and adjust the request
`413`	Request body exceeds 2MiB (`COMMON_REQUEST_BODY_TOO_LARGE`)	Split the request into smaller parts
`429`	Rate limit exceeded	Wait for the seconds in the `Retry-After` header and retry. See Rate limit
`5xx`	Server error or external provider outage	Retry with exponential backoff

Common error codes

These codes can occur on any endpoint. Write the handling logic for them once and reuse it across all calls.

Code	HTTP	Description
`COMMON_BINDING`	400	The request body could not be parsed (malformed JSON, etc.)
`COMMON_VALIDATION`	400	Field validation failed. `details` lists the violations
`COMMON_INVALID_CURSOR`	400	Invalid cursor format. Start again from the first page
`PLATFORM_INVALID_ID`	400	Invalid resource ID format. This is a format problem, not a missing resource, so it is `400` rather than `404`
`COMMON_UNAUTHORIZED`	401	Authentication failed
`INSUFFICIENT_CREDITS`	402	Insufficient credits
`COMMON_REQUEST_BODY_TOO_LARGE`	413	Request body exceeds 2MiB
`PLATFORM_RATE_LIMIT_EXCEEDED`	429	Rate limit exceeded

Endpoint-specific errors

Codes that only occur on a specific resource, such as PROMPT_SET_NOT_FOUND or RUN_TOO_MANY_TASKS, are not covered here. The Errors table at the top of each API Reference page lists only the codes that endpoint actually returns. The table is generated from the API spec, so it always matches the server.

The code prefix identifies the resource. Prompts use QUESTION_, brands use USER_BRAND_, prompt sets use PROMPT_SET_, and run requests use RUN_.

Retry strategy

429: wait for the number of seconds in the Retry-After header, then retry.
502 / 503: this may be an external provider outage. Retry with exponential backoff (for example, 1s, then 2s, then 4s).
400 / 404: retrying returns the same result. Fix the request instead.
If a transient error occurs while polling, collection for the run continues in the background. Pick up where you left off on the next poll.

Getting started

AI models

Authentication

Guides

MCP

HTTP status codes

Common error codes

Endpoint-specific errors

Retry strategy