Errors
Error codes returned by the HeyTaco API.
Error responses
When something goes wrong, we'll send you an error response in the following format:
code
Stable and code-safe; use this for conditional logic or error handling.
message
The helper message. You may use it for logging and debugging, but do not branch on its value — it may change over time.
{
"error": {
"code": "not_authenticated",
"message": "Provide your API token as a Bearer token in the Authorization header."
}
}Our error code catalog
Below are all of our expected error responses, where they happen, and some guidance on how to handle them.
not_authenticated
Missing or malformed Authorization header.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_token
Unknown, revoked, or expired token.
Returned by (1)
- GET/leaderboard — Get a leaderboard
https_required
The request was made over plain HTTP. Use https://.
Returned by (1)
- GET/leaderboard — Get a leaderboard
insufficient_scope
Token lacks a required scope.
Returned by (1)
- GET/leaderboard — Get a leaderboard
leaderboard_type_not_enabled
The requested leaderboard type is not enabled for this workspace. Returned to leaderboard-scoped tokens; leaderboard:all tokens bypass this check.
Returned by (1)
- GET/leaderboard — Get a leaderboard
api_disabled
The team has disabled API access.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_request
Unknown parameter, missing required field, or cross-field rule violation.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_type
type is not one of received | given | combined.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_timeframe
timeframe is not in the allowed set or violates the combined-only rule.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_channel
channel_id was empty or invalid.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_timezone
timezone is not a recognized time zone.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_date_range
start_date/end_date failed format or ordering rules.
Returned by (1)
- GET/leaderboard — Get a leaderboard
date_range_too_large
Custom range exceeds the 2-year maximum.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_limit
limit was not a positive integer.
Returned by (1)
- GET/leaderboard — Get a leaderboard
rate_limited
Rate limit exceeded — see Retry-After and the RateLimit-* headers.
Returned by (1)
- GET/leaderboard — Get a leaderboard
team_inactive
The workspace is deactivated in HeyTaco (e.g. the subscription has lapsed).
Returned by (1)
- GET/leaderboard — Get a leaderboard
user_inactive
The user who owns the token has been deactivated. Their tokens are revoked in the same operation, but a token in a mid-flight request may still surface this code.
Returned by (1)
- GET/leaderboard — Get a leaderboard
invalid_team
The workspace could not be found by the upstream service.
Returned by (1)
- GET/leaderboard — Get a leaderboard
user_not_in_team
The token's owner is no longer a member of the workspace.
Returned by (1)
- GET/leaderboard — Get a leaderboard
service_unavailable
A dependent service is unreachable or returned a 5xx. Retry with backoff.
Returned by (1)
- GET/leaderboard — Get a leaderboard
internal_error
An unexpected server-side error. Not caused by the request.
Returned by (1)
- GET/leaderboard — Get a leaderboard