Check if a referral code exists and is available for use.

When to Use This Endpoint

• Validate codes before submission: Check if a code exists and is still usable before attempting to use it with PATCH /v1/referral_codes/{code}/use
• Client-side validation: Provide real-time feedback in your UI when users enter referral codes (e.g., "Code valid ✓" or "Code expired ✗")
• Pre-display code availability: Show users whether a referral code they're about to share is still active
• Integration testing: Verify code generation and usage workflows
• Public code verification: Allow anyone to check if a code exists without requiring service_role permissions

When NOT to Use This Endpoint

• Don't use for code ownership verification: This endpoint only checks availability, not who owns the code (use GET /v1/referral_codes?user_identifier=... for ownership)
• Don't use to get detailed code metadata: This returns only available: true/false. For full code details (owner, creation date, usage count), use other endpoints
• Don't use for actual code application: After validating, you must still call PATCH /v1/referral_codes/{code}/use to actually apply the code

How Availability Works

A code is considered available (available: true) when:

• The code exists in the system, AND
• Either the code has unlimited uses (max_uses is null)
• OR the code has remaining uses (current_uses < max_uses)

A code returns unavailable (available: false) when:

• The code does not exist, OR
• The code has reached its maximum uses (current_uses >= max_uses)

Important Constraints

• Required API Key Scope: referral_codes:read (less restrictive than other referral code operations)
• Rate Limit: 100 requests/minute (standard rate)
• Case-sensitive: Referral codes are case-sensitive (ABC1234 ≠ abc1234)
• Code format: Codes are 7-character alphanumeric strings
• No usage details: This endpoint does NOT return usage count, owner info, or creation date (only availability boolean)

Response Behavior

This endpoint always returns 200 OK with {"available": true} or {"available": false}:

• ✅ Code exists with remaining uses → {"available": true}
• ✅ Code exists with unlimited uses → {"available": true}
• ❌ Code exists but max uses reached → {"available": false}
• ❌ Code does not exist → {"available": false}

Note: You cannot distinguish between "code doesn't exist" and "code exhausted" from this endpoint alone.

Common Errors

• 401 Unauthorized: Missing or invalid API key, or API key lacks referral_codes:read scope
• 429 Too Many Requests: Rate limit exceeded (100 requests/minute)

Related Endpoints

• PATCH /v1/referral_codes/{code}/use - Actually apply the referral code to a user (after validation)
• GET /v1/referral_codes - Get all codes owned by a specific user
• POST /v1/referral_codes - Generate new referral codes in batch
• GET /v1/referral_codes/status - Check if a specific user has already used a referral code

Best Practices

1. Validate before use: Always call this endpoint before showing a "use code" button to users
2. Cache wisely: Code availability can change rapidly (as users use codes), so cache responses for only 5-10 seconds
3. Handle both states: Design your UI to gracefully handle both available and unavailable states
4. Provide clear feedback: When available: false, explain to users that the code may be expired or invalid (without revealing which)