REST API

Errors

HTTP status codes and error response format. The codes below are universal; the response body fields are Appice-specific.

Status codes

Code	Meaning	Common causes
`200`	OK	Request succeeded.
`201`	Created	Resource created.
`202`	Accepted	Event accepted for asynchronous processing.
`400`	Bad Request	Malformed JSON, missing required field, invalid type.
`401`	Unauthorized	Missing, invalid or expired API token.
`403`	Forbidden	Token does not carry the required scope.
`404`	Not Found	Resource does not exist.
`409`	Conflict	Idempotency key collision with a different payload.
`422`	Unprocessable Entity	Schema-valid but business-rule-rejected.
`429`	Too Many Requests	Rate limit exceeded — see `Retry-After` header.
`500`	Internal Server Error	Server-side failure — retry with exponential backoff.
`503`	Service Unavailable	Brief unavailability — retry.

Error response body

⚠ TODO — Engineering

Document the canonical error response shape. Common pattern: { error: { code, message, request_id, details } }. Include a worked example for a 400 and a 401.

Retry strategy

For 5xx and 429 responses, retry with exponential backoff. Recommended: initial delay 1s, multiplier 2x, max delay 30s, max attempts 5. Honor the Retry-After header on 429 responses if present.