Claude API — Authentication, Rate Limits và Error Handling

Giới thiệu

Làm việc với Claude API đòi hỏi hiểu rõ ba khía cạnh nền tảng: xác thực (authentication), giới hạn tốc độ (rate limits), và xử lý lỗi (error handling). Đây không chỉ là kiến thức "nice to have" — thiếu chúng, ứng dụng của bạn sẽ thất bại trong production khi tải cao.

Bài viết này đi sâu vào từng khía cạnh với code examples thực tế, giải thích rõ ràng các error codes, và các patterns tốt nhất để xây dựng ứng dụng API production-ready.

Authentication — Xác thực với Claude API

API Keys là gì?

Claude API sử dụng API key để xác thực mọi request. API key là một chuỗi ký tự bắt đầu bằng sk-ant- — đây là credential duy nhất để Anthropic nhận biết request đến từ tổ chức/người dùng nào.

Có hai loại API key trong hệ thống Anthropic:

• Organization API keys: Tạo và quản lý tại console.anthropic.com, thuộc về organization, dùng cho production workloads
• Personal API keys: Liên kết với tài khoản cá nhân, phù hợp cho development và testing

Tạo và quản lý API Key

Để tạo API key mới:

1. Đăng nhập vào console.anthropic.com
2. Vào API Keys trong sidebar
3. Click Create Key, đặt tên mô tả rõ mục đích (ví dụ: "production-app-v2", "dev-testing")
4. Copy key ngay lập tức — Anthropic chỉ hiển thị một lần

Lưu ý quan trọng: Anthropic không lưu API key sau khi tạo. Nếu mất key, bạn phải tạo key mới và revoke key cũ.

Sử dụng API Key trong code

Cách đúng để truyền API key là qua header x-api-key:

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: YOUR_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Trong Python với SDK chính thức:

import anthropic
import os

# Đọc từ environment variable — KHÔNG hardcode key trong code
client = anthropic.Anthropic(
    api_key=os.environ.get("ANTHROPIC_API_KEY")
)

message = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)
print(message.content[0].text)

Trong Node.js/TypeScript:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

const message = await client.messages.create({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Hello" }],
});

console.log(message.content[0].text);

Best practices bảo mật API Key

• Dùng environment variables: Không bao giờ hardcode key trong source code
• Không commit vào git: Thêm .env vào .gitignore
• Rotate định kỳ: Tạo key mới và revoke key cũ theo lịch (ví dụ: 90 ngày)
• Principle of least privilege: Tạo key riêng cho từng environment (dev, staging, production)
• Monitor usage: Theo dõi usage dashboard để phát hiện bất thường

Header bắt buộc

Mỗi request đến Claude API cần các headers sau:

Header	Giá trị	Bắt buộc
x-api-key	API key của bạn	Có
anthropic-version	2023-06-01	Có
content-type	application/json	Có
anthropic-beta	Tên beta feature	Không (chỉ khi dùng beta)

Rate Limits — Hiểu và xử lý giới hạn tốc độ

Cấu trúc Rate Limits

Anthropic áp dụng rate limits theo nhiều chiều đồng thời:

• RPM (Requests Per Minute): Số request tối đa mỗi phút
• TPM (Tokens Per Minute): Số token (input + output) tối đa mỗi phút
• ITPM (Input Tokens Per Minute): Số input token tối đa mỗi phút

Rate limits khác nhau theo tier và model. Khi mới tạo tài khoản, bạn bắt đầu ở Tier 1 và tăng dần khi spend nhiều hơn:

Tier	Điều kiện	Claude Sonnet 4 RPM	TPM
Tier 1	Mới đăng ký	50	40,000
Tier 2	Đã spend $40+	1,000	80,000
Tier 3	Đã spend $200+	2,000	160,000
Tier 4	Đã spend $400+	4,000	400,000

Số liệu chính xác thay đổi theo thời gian — kiểm tra trang docs.anthropic.com/rate-limits để có thông tin mới nhất.

Headers rate limit trong response

Mỗi API response trả về headers cho biết trạng thái rate limit hiện tại:

anthropic-ratelimit-requests-limit: 1000
anthropic-ratelimit-requests-remaining: 999
anthropic-ratelimit-requests-reset: 2024-12-01T00:00:00Z
anthropic-ratelimit-tokens-limit: 80000
anthropic-ratelimit-tokens-remaining: 79500
anthropic-ratelimit-tokens-reset: 2024-12-01T00:01:00Z

Đọc các headers này để chủ động điều chỉnh rate của ứng dụng trước khi bị hit limit.

Error Codes — Xử lý từng loại lỗi

Tổng quan HTTP Status Codes

Status Code	Tên lỗi	Nguyên nhân thường gặp
400	Bad Request	Request format sai, field thiếu, giá trị không hợp lệ
401	Unauthorized	API key thiếu hoặc không hợp lệ
403	Forbidden	API key không có quyền, region bị block
404	Not Found	Endpoint không tồn tại
429	Too Many Requests	Vượt rate limit
500	Internal Server Error	Lỗi phía Anthropic
529	Overloaded	API đang quá tải, thử lại sau

Error response format

Khi có lỗi, API trả về JSON với cấu trúc:

{
  "type": "error",
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded for model claude-sonnet-4-5"
  }
}

Các error type phổ biến:

• invalid_request_error — lỗi 400, request không hợp lệ
• authentication_error — lỗi 401, API key sai
• permission_error — lỗi 403, không có quyền
• not_found_error — lỗi 404
• rate_limit_error — lỗi 429, vượt rate limit
• api_error — lỗi 500, server error
• overloaded_error — lỗi 529, quá tải

Retry Strategy — Xử lý lỗi thông minh

Exponential Backoff

Khi gặp lỗi 429 hoặc 529, không retry ngay lập tức — hãy dùng exponential backoff với jitter:

import anthropic
import time
import random

def make_request_with_retry(client, max_retries=5, **kwargs):
    """
    Gửi request với exponential backoff retry.
    """
    for attempt in range(max_retries):
        try:
            return client.messages.create(**kwargs)
        except anthropic.RateLimitError as e:
            if attempt == max_retries - 1:
                raise  # Re-raise sau khi hết số lần retry

            # Exponential backoff: 1s, 2s, 4s, 8s, 16s
            base_delay = 2 ** attempt
            # Thêm jitter để tránh thundering herd
            jitter = random.uniform(0, 1)
            delay = base_delay + jitter

            print(f"Rate limited. Retrying in {delay:.2f}s (attempt {attempt + 1}/{max_retries})")
            time.sleep(delay)
        except anthropic.APIStatusError as e:
            if e.status_code == 529:  # Overloaded
                if attempt == max_retries - 1:
                    raise
                delay = 2 ** attempt + random.uniform(0, 1)
                time.sleep(delay)
            else:
                raise  # Không retry các lỗi khác

# Sử dụng
client = anthropic.Anthropic()
response = make_request_with_retry(
    client,
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}]
)

SDK built-in retry

Anthropic SDK có sẵn retry mechanism. Bạn có thể configure khi khởi tạo client:

import anthropic

# Python SDK — tự động retry với exponential backoff
client = anthropic.Anthropic(
    max_retries=3,  # Mặc định là 2
)

# Hoặc disable retry hoàn toàn
client_no_retry = anthropic.Anthropic(
    max_retries=0,
)

import Anthropic from "@anthropic-ai/sdk";

// Node.js SDK
const client = new Anthropic({
  maxRetries: 3, // Mặc định là 2
  timeout: 20 * 1000, // 20 giây timeout
});

Khi nào retry, khi nào không

Error Code	Nên retry?	Lý do
400	Không	Request của bạn sai, fix code trước
401	Không	API key sai, không có lý do retry
403	Không	Vấn đề quyền hạn, cần can thiệp thủ công
429	Có (với backoff)	Tạm thời, sẽ hết sau một thời gian
500	Có (giới hạn)	Có thể là lỗi tạm thời phía server
529	Có (với backoff dài)	API quá tải, cần đợi lâu hơn

Request và Response Format

Cấu trúc request cơ bản

{
  "model": "claude-sonnet-4-5",
  "max_tokens": 1024,
  "messages": [
    {
      "role": "user",
      "content": "Giải thích recursion bằng ví dụ đơn giản"
    }
  ],
  "system": "Bạn là giáo viên lập trình thân thiện.",
  "temperature": 0.7,
  "stream": false
}

Các parameters quan trọng:

• model: Model ID (claude-opus-4, claude-sonnet-4-5, claude-haiku-3-5)
• max_tokens: Số token output tối đa — bắt buộc phải truyền
• messages: Array các tin nhắn theo turn (user/assistant)
• system: System prompt — không nằm trong messages array
• temperature: 0.0 (deterministic) đến 1.0 (creative), mặc định 1.0
• stream: Bật streaming mode

Cấu trúc response

{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Recursion là khi một hàm gọi chính nó..."
    }
  ],
  "model": "claude-sonnet-4-5",
  "stop_reason": "end_turn",
  "stop_sequence": null,
  "usage": {
    "input_tokens": 25,
    "output_tokens": 156
  }
}

Trường stop_reason cho biết tại sao generation dừng:

• end_turn — model kết thúc tự nhiên
• max_tokens — đạt giới hạn max_tokens, response có thể bị cắt
• stop_sequence — gặp stop sequence được định nghĩa
• tool_use — model muốn sử dụng tool

SDK Error Handling Patterns

Python — xử lý toàn diện

import anthropic
import logging

logger = logging.getLogger(__name__)

def safe_claude_call(client, **kwargs):
    try:
        response = client.messages.create(**kwargs)

        # Kiểm tra response bị cắt
        if response.stop_reason == "max_tokens":
            logger.warning("Response bị cắt do max_tokens. Tăng max_tokens nếu cần.")

        return response

    except anthropic.AuthenticationError:
        logger.error("API key không hợp lệ. Kiểm tra ANTHROPIC_API_KEY.")
        raise
    except anthropic.PermissionDeniedError:
        logger.error("Không có quyền. Kiểm tra API key permissions.")
        raise
    except anthropic.BadRequestError as e:
        logger.error(f"Request không hợp lệ: {e.message}")
        raise
    except anthropic.RateLimitError:
        logger.warning("Rate limit exceeded. SDK sẽ tự retry.")
        raise
    except anthropic.APIStatusError as e:
        logger.error(f"API error {e.status_code}: {e.message}")
        raise
    except anthropic.APIConnectionError:
        logger.error("Không thể kết nối tới Anthropic API. Kiểm tra network.")
        raise

TypeScript — với type safety

import Anthropic from "@anthropic-ai/sdk";

async function safeClaude(
  client: Anthropic,
  params: Anthropic.MessageCreateParamsNonStreaming
): Promise {
  try {
    const response = await client.messages.create(params);

    if (response.stop_reason === "max_tokens") {
      console.warn("Response truncated. Consider increasing max_tokens.");
    }

    return response;
  } catch (error) {
    if (error instanceof Anthropic.AuthenticationError) {
      throw new Error("Invalid API key");
    }
    if (error instanceof Anthropic.RateLimitError) {
      console.warn("Rate limited — SDK will retry automatically");
      throw error;
    }
    if (error instanceof Anthropic.APIError) {
      console.error(`API Error ${error.status}: ${error.message}`);
      throw error;
    }
    throw error;
  }
}

Streaming — Xử lý response real-time

Khi nào dùng streaming?

Thay vì đợi toàn bộ response rồi hiển thị một lần, streaming cho phép hiển thị từng token ngay khi được generate. Dùng streaming khi:

• Building chatbot UX — user thấy response ngay, không cảm giác "đóng băng"
• Response dài — không cần đợi hàng chục giây trước khi thấy gì
• Muốn allow user cancel generation sớm

Streaming với Python SDK

import anthropic

client = anthropic.Anthropic()

# Streaming với context manager
with client.messages.stream(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Giải thích về black holes"}]
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

# Lấy final message sau khi stream xong
final_message = stream.get_final_message()
print(f"
Tokens used: {final_message.usage.input_tokens} in, {final_message.usage.output_tokens} out")

Streaming với Node.js SDK

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const stream = await client.messages.stream({
  model: "claude-sonnet-4-5",
  max_tokens: 1024,
  messages: [{ role: "user", content: "Giải thích về black holes" }],
});

for await (const chunk of stream) {
  if (
    chunk.type === "content_block_delta" &&
    chunk.delta.type === "text_delta"
  ) {
    process.stdout.write(chunk.delta.text);
  }
}

const finalMessage = await stream.finalMessage();
console.log(`
Usage: ${finalMessage.usage.input_tokens} in / ${finalMessage.usage.output_tokens} out`);

Rate limits và streaming

Streaming vẫn bị ảnh hưởng bởi rate limits. Một streaming request vẫn tính là một request cho RPM limit, và toàn bộ tokens (input + output) tính cho TPM limit. Error 429 có thể xảy ra trước khi stream bắt đầu, nhưng không xảy ra giữa chừng của stream.

Monitoring và Observability

Theo dõi usage

Mỗi response trả về usage object với số token đã dùng. Aggregate số liệu này để kiểm soát chi phí:

class UsageTracker:
    def __init__(self):
        self.total_input_tokens = 0
        self.total_output_tokens = 0
        self.request_count = 0

    def track(self, response):
        self.total_input_tokens += response.usage.input_tokens
        self.total_output_tokens += response.usage.output_tokens
        self.request_count += 1

    def cost_estimate_usd(self, model="claude-sonnet-4-5"):
        """Ước tính chi phí dựa trên usage."""
        pricing = {
            "claude-opus-4": (15.0, 75.0),      # (input, output) per 1M tokens
            "claude-sonnet-4-5": (3.0, 15.0),
            "claude-haiku-3-5": (0.80, 4.0),
        }
        input_price, output_price = pricing.get(model, (3.0, 15.0))
        cost = (self.total_input_tokens / 1_000_000 * input_price +
                self.total_output_tokens / 1_000_000 * output_price)
        return round(cost, 4)

Best Practices tổng hợp

Checklist trước khi deploy production

• API key security: Dùng secret manager (AWS Secrets Manager, HashiCorp Vault) thay vì env file
• Retry với backoff: Luôn handle 429 và 529 với exponential backoff
• Circuit breaker: Implement pattern để dừng gọi khi error rate cao
• Timeout: Set timeout hợp lý (30-60s cho request thông thường)
• Logging: Log error codes, không log API key hay nội dung nhạy cảm
• Usage monitoring: Alert khi token usage gần đến limit
• Graceful degradation: Fallback khi API không khả dụng

Common mistakes cần tránh

• Không set max_tokens — request sẽ bị từ chối
• Hardcode API key trong source code
• Không handle stop_reason == "max_tokens" — response bị cắt silently
• Retry tất cả error codes — không nên retry 400, 401, 403
• Không đọc rate limit headers — bỏ lỡ cơ hội điều chỉnh proactively

Kết luận

Authentication, rate limits, và error handling là ba trụ cột của một Claude API integration bền vững. Bắt đầu với API key management đúng cách, implement exponential backoff cho rate limit errors, và handle từng error code phù hợp.

SDK chính thức của Anthropic (Python và Node.js) đã xử lý nhiều edge cases tự động — hãy sử dụng chúng thay vì tự implement HTTP calls từ đầu. Đọc rate limit headers proactively và monitor token usage để tránh bị surprise bởi bills hay downtime.

---

Bài viết liên quan

• Anthropic Console — Quản lý API, billing và workbench
• Building Effective Agents với Claude — Hướng dẫn kiến trúc
• Context Engineering — Nghệ thuật quản lý context cho Claude
• Bắt đầu với Claude Vision — Gửi hình ảnh qua API
• Claude cho Data: Tạo biểu đồ và visualization