# GET /api/v1/usernames/check

Auth: public

HTML: https://cooperemail.com/docs/reference/username-check

## Summary

Public username check. Query name. Returns name, normalized, available, optional reason (invalid_username, reserved_username, or taken), and suggestions (up to 5 names that are valid, not reserved, and not already an inbox). No API key. 30 requests per minute per IP, then HTTP 429 rate_limited with Retry-After, retry_after_seconds, and resets_at. Responses include RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until the window ends; on HTTP 429 it matches Retry-After). A lookup that cannot be completed returns HTTP 503 username_check_unavailable with those retry fields. If the limit cannot be checked, the response is HTTP 503 rate_limit_unavailable with those retry fields. The body does not say who holds a name. MCP: check_username true on cooper_onboard or cooper_create_inbox.

## Request

This call has no JSON body.

## Response

HTTP 200. Sample values illustrate the schema.

```json
{
  "name": "string",
  "normalized": "string",
  "available": true,
  "suggestions": [
    "string"
  ]
}
```

## Errors

- HTTP 429 rate_limited
- HTTP 503 username_check_unavailable
- HTTP 503 rate_limit_unavailable

The live `message` is the sentence for that code. Branch on `code`.

```json
{
  "error": {
    "type": "rate_limit",
    "code": "rate_limited",
    "docs_url": "https://cooperemail.com/docs#rate_limited"
  }
}
```

## Idempotency

This route does not document Idempotency-Key or client_id.