API Reference

Errors

The Two Minute Reports API error envelope, status codes, and machine-readable error codes.

When a request fails, the API returns the standard envelope with success: false and an error object:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "name: String must contain at least 1 character(s)"
  }
}

code — a stable, machine-readable string. Branch on this in your code rather than parsing the message.
message — a human-readable description. For validation and business-rule errors it is specific; for authentication, authorization, and server errors it is intentionally generic to avoid leaking internal details.

Status codes

HTTP status	`code`	When it happens
`400`	`BAD_REQUEST`	Invalid input — failed request validation or a business-rule violation
`401`	`UNAUTHORIZED`	Missing, malformed, expired, or revoked token
`403`	`FORBIDDEN`	Authenticated, but lacking the required team role or access
`403`	`INSUFFICIENT_PERMISSIONS`	The API key lacks the scope the endpoint requires — the message names the missing scope
`404`	`NOT_FOUND`	The resource does not exist or is not visible to you
`409`	`CONFLICT`	Conflicts with current state (e.g. a duplicate invite)
`413`	`PAYLOAD_TOO_LARGE`	Request body exceeds the size limit
`422`	`VALIDATION_ERROR`	Semantic validation failure
`429`	`TOO_MANY_REQUESTS`	Rate limit exceeded
`402`	`PAYMENT_REQUIRED`	The team's plan is cancelled — reactivate to make changes
`500`	`INTERNAL_SERVER_ERROR`	An unexpected error on our side

Examples

{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "Invalid UUID: \"abc\""
  }
}

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to perform this action"
  }
}

The key is missing the scope this endpoint needs; the message names it.

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "This API key is missing the `clients:delete` permission required for this endpoint. Grant it to the key under Settings → API Keys (https://hub.twominutereports.com/settings?tab=api-keys), or use a key that has it."
  }
}

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "The requested resource was not found"
  }
}

{
  "success": false,
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Your team's plan has been cancelled. Please reactivate your subscription to continue."
  }
}

Rate limits

Request quotas for the Two Minute Reports API and how to handle the 429 Too Many Requests response.

Users

Read and update the authenticated user — profile, avatar, and preferences.