Xử lý lỗi

Nâng cao Cập nhật: 22/03/2026

Mã lỗi HTTP

HTTP Status	Mã lỗi	Mô tả	Cách xử lý
400	INVALID_REQUEST	Tham số không hợp lệ hoặc thiếu	Kiểm tra lại body/params
401	UNAUTHORIZED	API key không hợp lệ hoặc thiếu header	Kiểm tra API key và header Authorization
403	FORBIDDEN	Không có quyền truy cập tài nguyên	Kiểm tra quyền của API key
404	NOT_FOUND	Tài nguyên không tồn tại	Kiểm tra ID hoặc slug
429	RATE_LIMIT_EXCEEDED	Vượt giới hạn 60 req/phút	Chờ theo `retry_after` giây
500	INTERNAL_ERROR	Lỗi nội bộ server	Thử lại sau, liên hệ support nếu tiếp diễn

Định dạng Response lỗi

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Retry after 45 seconds.",
    "retry_after": 45
  }
}

Xử lý Rate Limit (429)

<?php
// PHP: Retry với exponential backoff
function requestWithRetry(string $url, array $headers, int $maxRetries = 3): array
{
    $delay = 1;
    for ($i = 0; $i < $maxRetries; $i++) {
        $ch = curl_init($url);
        curl_setopt_array($ch, [
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => $headers,
        ]);
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);

        if ($httpCode === 429) {
            $data       = json_decode($response, true);
            $retryAfter = $data['error']['retry_after'] ?? $delay;
            error_log("Rate limit, thử lại sau {$retryAfter}s (lần " . ($i + 1) . ")");
            sleep($retryAfter);
            $delay *= 2; // Exponential backoff
            continue;
        }

        return ['code' => $httpCode, 'body' => json_decode($response, true)];
    }

    throw new RuntimeException('Đã vượt quá số lần thử lại');
}

// Node.js: Retry với exponential backoff
async function requestWithRetry(url, options, maxRetries = 3) {
    let delay = 1000; // 1 giây

    for (let i = 0; i < maxRetries; i++) {
        try {
            const response = await axios(url, options);
            return response.data;
        } catch (error) {
            if (error.response?.status === 429) {
                const retryAfter = error.response.data.error.retry_after || delay / 1000;
                console.warn(`Rate limit, thử lại sau ${retryAfter}s`);
                await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
                delay *= 2;
                continue;
            }
            throw error; // Lỗi khác — không retry
        }
    }
    throw new Error('Đã vượt quá số lần thử lại');
}

Idempotency — Tránh xử lý trùng

ThueAPI có thể gửi lại webhook nếu server của bạn không phản hồi kịp. Luôn kiểm tra transactionNumber trước khi xử lý:

<?php
// Kiểm tra trùng lặp trước khi xử lý
$txNumber = $transaction['transactionNumber'];
$exists   = Transaction::where('transaction_number', $txNumber)->exists();

if ($exists) {
    // Trả về success nhưng không xử lý lại
    return response()->json(['success' => true]);
}

// Xử lý giao dịch mới
Transaction::create([...]);