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

Permission and seat errors

These are separate codes rather than one FORBIDDEN, because each has a different fix and a client that cannot tell them apart cannot tell the caller what to do. See Roles & Permissions.

HTTP status	`code`	What it means	How to fix it
`403`	`SEAT_REQUIRED`	The key holder's role allows this, but they have no seat in the team. Every permission that needs a seat is withheld.	Ask an Admin to assign them a seat. Changing their role will not help.
`403`	`ROLE_NOT_ASSIGNABLE`	You tried to assign a role that includes permissions you do not hold yourself.	Ask someone with those permissions to assign it.
`403`	`CANNOT_ACT_ON_MEMBER`	The member you are changing holds permissions you do not. Roles are only editable downwards, and an equal role counts as not-below.	Ask an Admin.
`403`	`CANNOT_ACT_ON_SELF`	You cannot change your own role or seat, not even to reduce it.	Ask another Admin to do it.
`403`	`CANNOT_ACT_ON_OWNER`	The team owner cannot be re-roled or removed by anybody.	Contact support to change who the owner is.
`402`	`SEAT_LIMIT_REACHED`	Every seat on the plan is assigned.	Un-assign a seat, or add seats to the plan.
`429`	`RATE_LIMITED`	An abuse cap on a specific endpoint, separate from the general rate limit. Invites are capped per team.	Back off and retry.

SEAT_REQUIRED and FORBIDDEN look similar and are not the same problem. FORBIDDEN means the role does not include the action — somebody has to change the role. SEAT_REQUIRED means the role does include it and nobody has assigned a seat — somebody has to assign one. Telling a customer the wrong one sends them to the wrong colleague.

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=user-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.