Skip to main content
This page covers advanced topics you’ll need for production use of the Team API.

​
Understanding Token Abilities

Team API tokens use a granular permission system based on abilities. Each token can have one or more abilities that control which resources it can access and which operations it can perform.

​
Read vs Write Scopes

Abilities are organized into read and write scopes:
  • Read abilities (e.g., read:team, read:domains) allow tokens to view resources and retrieve information
  • Write abilities (e.g., write:projects, write:webhooks) allow tokens to create, update, and delete resources
Write abilities implicitly include read access for the same resource.

​
Available Abilities

For a complete list of available abilities and their descriptions, see the Token abilities table in the Team API tokens guide.

​
Insufficient Permissions

If a token attempts an operation without the required ability, the API returns a 403 Forbidden error: 
{
  "error": {
    "code": "FORBIDDEN",
    "message": "This token does not have the required abilities to perform this action."
  }
}
Grant tokens only the abilities they need to perform their intended functions. This principle of least privilege improves security.

​
Working with Rate Limits

The Team API implements rate limiting to ensure fair usage and platform stability. Different rate limits apply based on the operation type.

​
Rate Limit Tiers

  • Read operations: 300 requests per minute (GET endpoints)
  • Write operations: 60 requests per minute (POST, PUT, DELETE endpoints)
  • Special endpoints: 3-10 requests per minute (e.g., token rotation, DNS verification)

​
Rate Limit Headers

Every API response includes headers showing your current rate limit status: 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 245
X-RateLimit-Reset: 1705843200

​
Handling Rate Limit Errors

When you exceed the rate limit, the API returns a 429 Too Many Requests response: 
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "retry_after": 42
  }
}
Implement exponential backoff when you receive a 429 error. Use the retry_after value in seconds or the X-RateLimit-Reset header to determine when to retry.

​
Error Handling

The Team API uses standard HTTP status codes to indicate the success or failure of requests.

​
Common Status Codes

StatusDescription
200 OKRequest succeeded
201 CreatedResource created successfully
400 Bad RequestInvalid request format or parameters
401 UnauthorizedMissing or invalid authentication token
403 ForbiddenToken lacks required abilities
404 Not FoundResource does not exist
422 Unprocessable EntityValidation error
429 Too Many RequestsRate limit exceeded
500 Internal Server ErrorServer error (contact support)

​
Error Response Format

All error responses follow a consistent format: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}

​
Validation Errors

Validation errors (422) include detailed field-level errors: 
{
  "message": "The given data was invalid.",
  "errors": {
    "domain": ["The domain has already been taken."],
    "name": ["The name field is required."]
  }
}
Always check the HTTP status code before parsing response bodies. Log request IDs from headers for troubleshooting with support.

​
Next Steps