PHP에서 API 타임아웃, 레이트 리밋 및 재시도 처리 방법
연결 타임아웃, HTTP 오류 처리, 지수 백오프, Retry-After 지원 및 안전한 재시도 전략을 사용하여 신뢰할 수 있는 PHP API 통합을 구축하는 방법을 배워보세요.
PHP에서 API 타임아웃, 레이트 리밋 및 재시도 처리하는 방법
API 통합은 개발 중에는 완벽하게 작동합니다. 그러다 어느 날, 예약된 작업이 중간에 멈춥니다. 원격 서비스가 HTTP 429로 응답하거나, 연결이 시간 초과되거나, HTTP 503 오류가 동기화를 중단합니다.
요청을 즉시 재시도하고 싶은 유혹이 생깁니다.
하지만 전략 없이 재시도하면 문제가 더 악화될 수 있습니다. 이미 어려움을 겪고 있는 API에 과부하를 걸거나, 요청 제한을 초과하거나, 실수로 중복 주문 및 결제를 생성할 수 있습니다.
신뢰할 수 있는 API 클라이언트에는 성공적인 curl_exec() 호출만으로는 충분하지 않습니다.
이 튜토리얼에서는 연결 타임아웃, HTTP 오류, 요청 제한 및 일시적 오류를 처리하는 실용적인 PHP HTTP 클라이언트를 구축합니다. 또한 재시도가 안전한 경우, 안전하지 않은 경우, 그리고 프로덕션에서 문제를 진단하는 방법에 대해 설명합니다.
예제에서는 Composer나 서드파티 의존성 없이 PHP 내장 cURL 확장을 사용합니다.
1. API 오류 유형 이해하기
모든 실패한 요청을 동일하게 처리해서는 안 됩니다.
| 오류 | 일반적인 원인 | 권장 조치 |
|---|---|---|
| 연결 타임아웃 | 서버에 도달할 수 없거나 느린 연결 | 신중하게 재시도 |
| HTTP 400 | 잘못된 요청 매개변수 | 요청 수정 |
| HTTP 401 | 잘못되었거나 만료된 자격 증명 | 인증 확인 |
| HTTP 404 | 리소스를 찾을 수 없음 | 리소스 식별자 확인 |
| HTTP 429 | API 요청 제한 초과 | Retry-After 준수 |
| HTTP 500 | 내부 서버 오류 | 선택적으로 재시도 |
| HTTP 503 | 일시적 서비스 이용 불가 | 지연 후 재시도 |
| 잘못된 JSON | 예상치 못한 응답 형식 | 기록 및 조사 |
네트워크 오류는 HTTP 오류와도 다릅니다.
API가 HTTP 500을 반환하면 HTTP 요청이 완료되었고 서버가 오류 응답을 반환한 것입니다.
cURL이 연결 실패를 보고하면 애플리케이션이 HTTP 응답을 전혀 수신하지 못했을 수도 있습니다.
이 구분은 재시도 여부를 결정할 때 중요합니다.
2. 항상 연결 및 요청 타임아웃 구성하기
PHP cURL은 특히 유용한 두 가지 설정을 제공합니다:
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_CONNECTTIMEOUT은 연결 단계를 제한하고, CURLOPT_TIMEOUT은 전체 전송 시간을 제한합니다. 둘 다 PHP 공식 cURL 참조 문서에 설명되어 있습니다.
적절한 제한이 없으면 느린 외부 서비스가 예상보다 훨씬 오래 PHP 워커를 점유할 수 있습니다.
일반적인 JSON API의 실용적인 시작점은 연결 설정에 5초, 전체 요청에 15초일 수 있습니다.
이것은 보편적인 값이 아닙니다. 파일 업로드나 오래 실행되는 보고서 생성에는 다른 타임아웃 정책이 필요할 수 있습니다.
첫 번째 API 요청하기
<?php
declare(strict_types=1);
$url = 'https://api.example.com/products';
$curl = curl_init($url);
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_FOLLOWLOCATION => false,
]);
$response = curl_exec($curl);
$statusCode = curl_getinfo(
$curl,
CURLINFO_HTTP_CODE
);
if ($response === false) {
$error = curl_error($curl);
curl_close($curl);
throw new RuntimeException(
'API request failed: ' . $error
);
}
curl_close($curl);
echo 'HTTP status: ' . $statusCode;
이것은 유용한 기반을 마련하지만, 아직 요청 제한이나 재시도 가능한 오류를 처리하지 않습니다.
3. HTTP 429 및 Retry-After 이해하기
HTTP 429는 클라이언트가 API 제공자가 정의한 기간 내에 너무 많은 요청을 보냈다는 것을 의미합니다.
일부 API는 분당, 시간당, API 키별 또는 계정별로 제한을 적용합니다.
서버가 다음과 같이 응답할 수 있습니다:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
Retry-After 헤더는 클라이언트에게 다시 시도하기 전에 얼마나 기다려야 하는지 알려줍니다.
헤더에는 초 단위 숫자 또는 HTTP 날짜가 포함될 수 있습니다.
예를 들어:
Retry-After: 120
또는:
Retry-After: Wed, 25 Nov 2026 10:00:00 GMT
정상적인 클라이언트는 요청을 반복적으로 보내는 대신 이 지시를 준수해야 합니다.
서버가 재시도 지연을 제공하지 않으면 애플리케이션에 대체 전략이 필요합니다.
4. 즉시 재시도 대신 지수 백오프 사용하기
지수 백오프는 연속된 오류 후 대기 시간을 늘립니다.
예를 들어:
| 재시도 | 예시 지연 |
|---|---|
| 1 | 1초 |
| 2 | 2초 |
| 3 | 4초 |
| 4 | 8초 |
매초 재시도하는 대신, 애플리케이션은 점진적으로 더 오래 기다립니다.
지터(jitter)라고 하는 작은 무작위 변동을 추가하면 많은 클라이언트가 동시에 재시도하는 것을 방지하는 데 도움이 됩니다.
다음은 재사용 가능한 지연 함수입니다:
<?php
declare(strict_types=1);
function getRetryDelayMs(int $attempt): int
{
$baseDelay = 1000;
$maximumDelay = 30000;
$exponentialDelay = min(
$maximumDelay,
$baseDelay * (2 ** ($attempt - 1))
);
return random_int(
0,
(int)$exponentialDelay
);
}
이것은 전체 지터를 사용합니다: 실제 지연은 0과 지수 상한 사이에서 무작위로 선택됩니다.
무작위 지연은 동기화된 재시도 폭주를 줄이지만, 서버가 제공한 명시적인 Retry-After 지시를 대체하지는 않습니다.

5. 재사용 가능한 PHP API 클라이언트 구축하기
이전 개념들을 결합하여 동작하는 구현을 만들어 보겠습니다.
우리 클라이언트는 다음을 수행합니다:
- 연결 및 전체 요청 타임아웃을 설정합니다.
- HTTP 상태 및 응답 본문을 반환합니다.
- 전송 오류를 감지합니다.
- 선택된 일시적 오류를 재시도합니다.
- 존재할 때
Retry-After을 준수합니다. - 시도 횟수를 제한합니다.
- 비멱등 작업을 자동으로 재시도하지 않습니다.
<?php
declare(strict_types=1);
/**
* Perform an HTTP GET request with bounded retries.
*
* Use only with trusted, configured API URLs.
*/
function apiGet(
string $url,
int $maxAttempts = 3
): array {
if ($maxAttempts < 1) {
throw new InvalidArgumentException(
'maxAttempts must be at least 1.'
);
}
for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
$headers = [];
$curl = curl_init($url);
if ($curl === false) {
throw new RuntimeException(
'Unable to initialize cURL.'
);
}
curl_setopt_array($curl, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CONNECTTIMEOUT => 5,
CURLOPT_TIMEOUT => 15,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_HTTPGET => true,
CURLOPT_HEADERFUNCTION => static function (
$curl,
string $headerLine
) use (&$headers): int {
$length = strlen($headerLine);
if (str_starts_with(
$headerLine,
'HTTP/'
)) {
$headers = [];
}
$position = strpos(
$headerLine,
':'
);
if ($position !== false) {
$name = strtolower(trim(
substr($headerLine, 0, $position)
));
$value = trim(
substr($headerLine, $position + 1)
);
$headers[$name] = $value;
}
return $length;
},
]);
$body = curl_exec($curl);
$curlError = curl_errno($curl);
$statusCode = (int)curl_getinfo(
$curl,
CURLINFO_HTTP_CODE
);
curl_close($curl);
$transportFailure = $body === false;
$retryableStatus = in_array(
$statusCode,
[408, 429, 500, 502, 503, 504],
true
);
if (!$transportFailure && !$retryableStatus) {
return [
'status' => $statusCode,
'body' => $body,
'headers' => $headers,
'attempts' => $attempt,
];
}
if ($attempt === $maxAttempts) {
throw new RuntimeException(
'API request failed after '
. $attempt
. ' attempts. HTTP '
. $statusCode
. ', cURL error '
. $curlError
);
}
$delayMs = min(
30000,
1000 * (2 ** ($attempt - 1))
);
$retryAfter = $headers['retry-after'] ?? null;
if ($retryAfter !== null) {
if (ctype_digit($retryAfter)) {
$delayMs = (int)$retryAfter * 1000;
} else {
$timestamp = strtotime($retryAfter);
if ($timestamp !== false) {
$delayMs = max(
0,
$timestamp - time()
) * 1000;
}
}
} else {
$delayMs = random_int(
0,
(int)$delayMs
);
}
// Do not block this worker indefinitely.
if ($delayMs > 30000) {
throw new RuntimeException(
'Retry deferred: waiting time exceeds '
. 'the synchronous retry budget.'
);
}
usleep((int)$delayMs * 1000);
}
throw new RuntimeException(
'Unexpected retry state.'
);
}
사용 방법
<?php
declare(strict_types=1);
try {
$result = apiGet(
'https://api.example.com/products'
);
if ($result['status'] !== 200) {
throw new RuntimeException(
'Unexpected HTTP status: '
. $result['status']
);
}
$products = json_decode(
$result['body'],
true,
512,
JSON_THROW_ON_ERROR
);
echo 'API request completed after '
. $result['attempts']
. ' attempt(s).';
} catch (Throwable $exception) {
error_log($exception->getMessage());
}
이 구현은 신뢰할 수 있는 API 엔드포인트에 대한 GET 요청으로 의도적으로 제한되어 있습니다.
추가 안전 장치가 필요하므로 POST, PUT, PATCH 또는 DELETE 작업은 자동으로 재시도하지 않습니다.
또한 재시도할 수 없는 HTTP 응답을 호출자에게 반환하며, 호출자가 이를 처리하는 방법을 결정해야 합니다.
프로덕션 시스템에서는 응답 유형을 검증하고, 응답 크기 제한을 적용하며, 재시도 가능한 전송 오류와 영구적인 TLS 또는 구성 오류를 구분해야 합니다.
6. POST 요청 재시도가 위험할 수 있는 이유
이커머스 애플리케이션이 이 요청을 보낸다고 상상해 보세요:
POST /api/orders
Content-Type: application/json
{
"product_id": 42,
"quantity": 1
}
원격 API가 주문을 생성하지만, 애플리케이션이 응답을 받기 전에 연결이 끊어집니다.
애플리케이션은 타임아웃을 감지합니다.
주문이 실패했을까요?
반드시 그렇지는 않습니다. 주문이 이미 존재할 수 있습니다.
애플리케이션이 즉시 재시도하면 두 번째 주문이 생성될 수 있습니다.
이것이 타임아웃이 서버에서 작업이 실패했음을 증명하지 않는다는 이유입니다.
지원되는 경우 멱등성 키 사용하기
일부 API는 멱등성 키를 지원합니다.
예를 들어:
Idempotency-Key: order-8f7a2c
API에 문서화된 멱등성 메커니즘이 있으면, 동일한 논리적 작업의 재시도에 동일한 키를 재사용하여 중복 처리를 방지할 수 있습니다.
하지만 이 동작은 API별입니다. Idempotency-Key 헤더를 추가한다고 해서 임의의 API가 자동으로 멱등해지는 것은 아닙니다.
결제, 주문, 구독 또는 데이터베이스 수정을 포함하는 작업의 경우 제공자의 공식 재시도 및 멱등성 문서를 따르십시오.
멱등성 메커니즘이 없는 경우, 다시 시도하기 전에 작업 상태를 조회하거나 결과를 조정해야 할 수 있습니다.
7. 오래 실행되는 웹 요청 안에서 sleep 사용 피하기

이 예제에서는 usleep()을 사용하여 재시도 동작을 쉽게 이해할 수 있게 합니다.
이는 재시도 예산이 철저히 제어된 짧은 작업에 대해서는 허용될 수 있습니다.
그러나 프로덕션 웹사이트가 외부 API를 기다리는 동안 PHP 워커를 몇 분 동안 점유하게 해서는 안 됩니다.
API가 다음과 같이 응답한다고 가정해 보세요:
HTTP/1.1 429 Too Many Requests
Retry-After: 3600
HTTP 요청 안에서 1시간을 기다리는 것은 나쁜 설계입니다.
더 나은 해결책은 작업을 유보하는 것입니다.
예를 들어, 대기 중인 작업을 저장합니다:
Job ID: 1842
Status: pending
Attempts: 2
Next attempt: 2026-11-20 14:30:00 UTC
그런 다음 예약된 워커가 작업이 적격해지면 처리할 수 있습니다.
이 접근 방식은 다음에 특히 유용합니다:
- 제품 카탈로그 동기화.
- 이메일 전송.
- 소셜 미디어 게시.
- 문서 처리.
- 재고 업데이트.
- 대규모 API 가져오기.
또한 오류를 모니터링하고 복구하기 쉽게 만듭니다.
8. 재시도 정보를 데이터베이스에 저장하기
MariaDB 기반 애플리케이션의 경우, 간단한 작업 테이블은 다음과 같을 수 있습니다:
CREATE TABLE api_jobs (
id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
job_type VARCHAR(100) NOT NULL,
payload_json LONGTEXT NOT NULL,
status VARCHAR(20) NOT NULL DEFAULT 'pending',
attempts INT UNSIGNED NOT NULL DEFAULT 0,
next_attempt_at DATETIME NOT NULL,
last_error TEXT NULL,
created_at DATETIME NOT NULL,
updated_at DATETIME NOT NULL,
INDEX idx_jobs_ready (
status,
next_attempt_at
)
);
워커는 다음 조건에 맞는 작업을 선택합니다:
SELECT id, job_type, payload_json
FROM api_jobs
WHERE status = 'pending'
AND next_attempt_at <= UTC_TIMESTAMP()
ORDER BY next_attempt_at, id
LIMIT 20;
이것은 큐 구현의 선택 부분만입니다.
여러 워커가 동시에 실행될 수 있는 경우, 중복 처리를 방지하기 위해 적절한 트랜잭션 및 잠금 전략을 사용하여 작업을 원자적으로 청구해야 합니다.
워커는 또한 최대 재시도 횟수를 적용하고 영구적으로 실패하는 작업을 조사가 필요한 상태로 이동해야 합니다.
소규모 애플리케이션에서는 Redis나 전용 메시지 브로커를 도입하지 않고도 이 데이터베이스 기반 접근 방식으로 충분할 수 있습니다.
9. 민감한 데이터를 노출하지 않고 오류 기록하기
유용한 API 로그는 네 가지 질문에 답해야 합니다:
- 어떤 작업이 실패했나요?
- 어떤 원격 서비스가 관련되었나요?
- HTTP 상태 또는 전송 오류는 무엇이었나요?
- 애플리케이션은 언제 재시도하나요?
예를 들어:
[2026-11-20 13:25:00 UTC]
service=inventory-api
operation=sync-products
status=429
attempt=2
next_retry=2026-11-20T13:26:00Z
API 키, 베어러 토큰, 전체 인증 헤더, 비밀번호 또는 불필요한 개인정보를 기록하지 마십시오.
요청을 상관관계 지어야 하는 경우 생성된 요청 식별자를 사용하십시오.
예를 들어:
$requestId = bin2hex(random_bytes(8));
이 식별자를 애플리케이션 로그에 포함시키고, 지원되는 경우 원격 API로 보낼 수 있습니다.
10. 프로덕션 전에 재시도 전략 테스트하기
재시도 메커니즘은 예측 가능한 오류 시나리오에 대해 테스트해야 합니다.
실제 API 장애를 기다릴 필요가 없습니다.
로컬 테스트 엔드포인트가 의도적으로 특정 상태 코드를 반환할 수 있습니다.
예를 들어:
<?php
declare(strict_types=1);
header('Content-Type: application/json');
http_response_code(429);
header('Retry-After: 3');
echo json_encode([
'error' => 'rate_limit_exceeded',
]);
이 엔드포인트는 로컬 또는 보호된 테스트 환경에서만 실행하십시오.
그런 다음 클라이언트가 다음을 수행하는지 확인합니다:
- HTTP 429를 감지합니다.
Retry-After헤더를 읽습니다.- 재시도 전에 대기합니다.
- 구성된 시도 횟수 후 중지합니다.
- 비밀을 노출하지 않고 오류를 기록합니다.
HTTP 503 및 의도적으로 느린 엔드포인트로 반복합니다.
또한 HTTP 400 응답을 테스트하여 클라이언트가 영구적인 요청 오류를 재시도하지 않는지 확인합니다.
마지막으로, 연결이 끊어지기 전에 성공했을 수 있는 작업을 테스트합니다. 이것은 결제 및 주문 통합에 필수적입니다.
11. 신뢰할 수 있는 API 통합을 위한 프로덕션 체크리스트
API 통합을 배포하기 전에 다음을 확인합니다:
| 확인 항목 | 예상 동작 |
|---|---|
| 연결 타임아웃 | 정의 및 테스트됨 |
| 전체 타임아웃 | 정의 및 테스트됨 |
| HTTP 429 | 요청 제한 준수 |
| HTTP 5xx | 선택적으로 재시도 |
| HTTP 4xx | 무분별한 재시도 없음 |
| 재시도 제한 | 무한 루프 방지 |
| 재시도 지연 | 지터가 있는 백오프 |
| POST 작업 | 멱등성 또는 조정 |
| 긴 대기 시간 | 워커로 유보 |
| 로그 | 유용하고, 비공개적이며, 정제됨 |
| 워커 동시성 | 중복 실행 방지 |
| 영구적 오류 | 표시 및 복구 가능 |
결론: 신뢰할 수 있는 API는 제어된 오류 처리를 필요로 합니다
외부 API는 완벽하게 사용 가능하지 않습니다.
잘 관리되는 서비스도 일시적 과부하, 네트워크 중단 또는 요청 제한을 경험할 수 있습니다.
목표는 모든 오류를 제거하는 것이 아닙니다. 오류가 발생했을 때 애플리케이션이 예측 가능하게 대응하도록 하는 것입니다.
합리적인 타임아웃과 명시적인 HTTP 오류 처리로 시작하십시오. 지수 백오프와 함께 제한된 재시도를 추가하고, 서버가 제공하는 재시도 지연을 준수하며, 중복 데이터를 생성할 수 있는 작업을 자동으로 반복하지 마십시오.
보다 복잡한 통합의 경우 웹 요청을 열어두는 대신 재시도를 영구적인 작업 큐로 옮기십시오.
이러한 원칙은 CMS 확장을 구축하거나, 이커머스 카탈로그를 동기화하거나, 트랜잭션 이메일을 보내거나, 결제 서비스를 통합하는 등 거의 모든 최신 PHP 애플리케이션에 적용됩니다.
신뢰할 수 있는 API 클라이언트는 요청을 보내는 방법뿐만 아니라 언제 재시도하고, 언제 기다리고, 언제 중단할지를 아는 클라이언트입니다.