Reference

Technical reference for Team API token abilities, rate limits, and error handling.

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

Status	Description
200 OK	Request succeeded
201 Created	Resource created successfully
400 Bad Request	Invalid request format or parameters
401 Unauthorized	Missing or invalid authentication token
403 Forbidden	Token lacks required abilities
404 Not Found	Resource does not exist
422 Unprocessable Entity	Validation error
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Server 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

• Use Cases & Best Practices - Explore common workflows and production guidance
• API Reference - View complete API documentation