Error Codes & Conventions

Every api/v1 endpoint follows the same rules.

Error Envelope

Errors use a flat JSON envelope. Branch on the stable code field:

{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"details": { ... }
}

Standard Codes

| HTTP | Code | Meaning |

|------|------|---------|

| 400 | BAD_REQUEST | Malformed request body or parameters |

| 401 | UNAUTHORIZED | Missing or invalid authentication |

| 403 | FORBIDDEN | Insufficient scopes |

| 404 | NOT_FOUND | Resource not found |

| 409 | CONFLICT | Resource conflict |

| 429 | RATE_LIMITED | Rate limit exceeded |

| 5xx | INTERNAL_ERROR | Server error |

Pagination

List endpoints are cursor-paginated. Pass ?limit= (1-200, default 50) and ?cursor=. The response carries next_cursor (null when no more results).