# Reference

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](/platform/teams/api-tokens#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:

```json
{
  "error": {
    "code": "FORBIDDEN",
    "message": "This token does not have the required abilities to perform this action."
  }
}
```

:::info
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:

```json
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later.",
    "retry_after": 42
  }
}
```

:::info
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:

```json
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  }
}
```

### Validation Errors

Validation errors (422) include detailed field-level errors:

```json
{
  "message": "The given data was invalid.",
  "errors": {
    "domain": ["The domain has already been taken."],
    "name": ["The name field is required."]
  }
}
```

:::tip
Always check the HTTP status code before parsing response bodies. Log request IDs from headers for troubleshooting with support.
:::

## SDK Notes

Official SDKs expose the Team API through team-scoped clients such as `Lettermint.api(...)`, `Lettermint::api(...)`, and `lettermint.NewAPI(...)`. These clients use bearer authentication and return typed responses where the language supports it.

- Pass pagination and filter values as query parameters, for example `page[size]`, `page[cursor]`, or `filter[search]`.
- Message `source`, `html`, and `text` endpoints return raw strings instead of JSON response objects.
- Use project tokens only with the Sending API. Team API clients require Team API tokens.

## Next Steps

- **[Use Cases & Best Practices](/platform/teams/team-api/use-cases)** - Explore common workflows and production guidance
- **[API Reference](/api-reference)** - View complete API documentation