Error Codes

All API errors return a JSON body with an error key.

Error format

{
  "error": "Human-readable error message"
}

For plan limit errors, an upgrade_url is also included:

{
  "error": "Free plan limit reached (50 wins). Upgrade to Pro for unlimited wins.",
  "upgrade_url": "https://app.myhypedoc.com/settings"
}

HTTP status codes

Status	Meaning	When
400	Bad Request	Missing required parameter
401	Unauthorized	Missing or invalid authentication token
402	Payment Required	Free plan limit reached
404	Not Found	Resource doesn’t exist or belongs to another user
422	Unprocessable Entity	Validation error (e.g. invalid data)
429	Too Many Requests	Rate limit exceeded

Common errors

401 Unauthorized

{
  "error": "Authentication required"
}

Your token is missing, invalid, or expired. Generate a new token in Settings → API Tokens.

402 Payment Required

{
  "error": "Free plan limit reached (50 wins). Upgrade to Pro for unlimited wins.",
  "upgrade_url": "https://app.myhypedoc.com/settings"
}

You’ve hit the free plan limit. Upgrade to Pro or delete existing resources.

404 Not Found

{
  "error": "Not found"
}

The resource doesn’t exist or belongs to another user. All resources are scoped to the authenticated user.

422 Unprocessable Entity

{
  "error": "Body can't be blank"
}

The request data failed validation. The error message describes what went wrong.

429 Too Many Requests

{
  "error": "Rate limit exceeded. Retry after 45 seconds."
}

You’ve exceeded the rate limit. Wait for the Retry-After duration before retrying. See Rate Limits.