API Response Codes — Reference | Document Stack Docs

Success Codes (2xx)

Code	Status	Description
200	OK	Request succeeded. Response body contains the requested data.
201	Created	Resource was successfully created (e.g., new template, project).
204	No Content	Request succeeded but no response body (e.g., after deletion).

Code	Status	Description	Common Cause
400	Bad Request	The request body is invalid or missing required fields.	Malformed JSON, missing required data fields
401	Unauthorized	Authentication failed or missing.	Missing or invalid API key, expired session
403	Forbidden	Authenticated but not authorized for this action.	Insufficient role permissions, wrong organization
404	Not Found	The requested resource does not exist.	Wrong template ID, deleted project
409	Conflict	Resource conflict.	Duplicate name, concurrent modification
413	Payload Too Large	Request body exceeds the 5MB limit.	Large data payload or embedded images
422	Unprocessable Entity	Request is well-formed but contains semantic errors.	Invalid field values, wrong data types
429	Too Many Requests	Rate limit exceeded.	Too many requests in a short period

Code	Status	Description	Action
500	Internal Server Error	An unexpected error occurred.	Retry the request; contact support if persistent
502	Bad Gateway	The server received an invalid response from upstream.	Wait and retry
503	Service Unavailable	The service is temporarily unavailable.	Wait and retry; check status page
504	Gateway Timeout	The request took too long to process.	Reduce document complexity; use async generation

All API responses follow a consistent JSON structure:

Field	Type	Description
success	boolean	Whether the request succeeded
data	object \| array	Response data (present on success)
error	string	Error message (present on failure)

Error Details

Error responses include a descriptive message in the error field. Use this message for debugging — it tells you exactly what went wrong.

When you receive a 429 response, check these headers:

Header	Description
Retry-After	Seconds to wait before retrying
X-RateLimit-Limit	Maximum requests allowed per window
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Timestamp when the rate limit resets

Status Code	Retry?	Strategy
400, 401, 403, 404, 413, 422	No	Fix the request; these are client errors
409	Maybe	Retry after resolving the conflict
429	Yes	Wait for Retry-After period, then retry
500	Yes	Retry with exponential backoff (max 3 attempts)
502, 503	Yes	Wait 5–30 seconds, then retry
504	Maybe	Simplify document or use async generation