Error codes
API errors return a JSON object with a human-readable error field:
{"error":"Authentication required"}Plan limit errors also include upgrade_url:
{ "error": "Plan limit reached", "upgrade_url": "https://app.myhypedoc.com/settings"}HTTP statuses
Section titled “HTTP statuses”| Status | Meaning | Typical cause |
|---|---|---|
400 | Bad request | Malformed JSON or request |
401 | Unauthenticated | Missing or invalid bearer token |
402 | Payment required | Free plan limit reached |
403 | Forbidden | Authenticated user lacks permission |
404 | Not found | Resource is missing or not visible |
422 | Validation failed | Invalid field, date, or state |
429 | Rate limited | Request limit exceeded |
The API uses 404 for resources that the caller cannot see, which avoids
revealing whether another user owns them.
Authentication error
Section titled “Authentication error”HTTP/1.1 401 UnauthorizedContent-Type: application/json{"error":"Authentication required"}Create a new token with the email code flow or in Settings.
Plan limit error
Section titled “Plan limit error”HTTP/1.1 402 Payment RequiredContent-Type: application/json{ "error": "Plan limit reached", "upgrade_url": "https://app.myhypedoc.com/settings"}The free plan allows 50 billable wins and 3 owned spaces. The limit is charged to the space owner.
Validation error
Section titled “Validation error”HTTP/1.1 422 Unprocessable EntityContent-Type: application/json{"error":"Body cannot be blank"}Use the message to correct the request, then retry.
Rate limit error
Section titled “Rate limit error”A 429 response includes Retry-After in seconds. See Rate limits.