HTTP Behavior

This section summarizes HTTP behavior rules shared across multiple endpoints.

Shared Rules

• REST APIs use real HTTP status codes and do not return 200 for all outcomes
• Response bodies use the unified response envelope
• Clients must branch on both HTTP status and response code
• Error responses omit data
• 429 RATE_LIMITED responses include Retry-After
• Side-effecting command retries must reuse the same Idempotency-Key

Recommended reading order:

1. Base URL and Headers
2. Permissions
3. Pagination
4. Rate Limits and Retries
5. Status Code Overview