---
title: "오류 처리"
slug: "api-call-std-errorhandling"
updated: 2026-10-22T10:46:03Z
published: 2026-10-22T10:46:03Z
canonical: "api-gov.ncloud-docs.com/api-call-std-errorhandling"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://api-gov.ncloud-docs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 오류 처리

VPC 환경에서 이용 가능합니다.

Ncloud API 표준 규격을 적용한 API입니다.

Standardized API 호출 실패 시 제공되는 오류 코드와 메시지 정보, 응답 구조를 설명합니다.

참고

- 오류 메시지는 기본적으로 영어로 제공하며, 일부 서비스는 한국어와 일본어 오류 메시지를 함께 제공합니다.
- 서비스별 오류 코드와 발생 조건은 각 서비스 API 가이드의 응답 상태 코드를 참조해 주십시오.

## 오류 코드

응답 상태 코드에 대한 설명은 다음과 같습니다. HTTP 상태 코드는 응답 헤더에 포함되며, 오류 코드는 응답 바디에 포함됩니다. 하나의 HTTP 상태 코드에 여러 오류 코드가 대응될 수 있으므로 오류를 처리할 때는 HTTP 상태 코드와 오류 코드를 함께 확인해 주십시오.

### 성공

호출이 성공한 경우의 상태 코드는 다음과 같습니다. 오류에 대한 조치가 필요 없습니다.

| HTTP 상태 코드 | 메시지 | 설명 |
| --- | --- | --- |
| `200 OK` | 성공 | 요청을 정상적으로 처리하고 응답 데이터를 반환한 경우 |
| `201 Created` | 생성 성공 | 자원 생성 요청을 정상적으로 처리한 경우 |
| `202 Accepted` | 요청 수락 | 요청을 수락하고 비동기로 처리를 진행하는 경우 |
| `204 No Content` | 성공 | 요청을 정상적으로 처리하고 반환할 응답 데이터가 없는 경우 |

참고

- 리소스 생성이나 대량 데이터 처리처럼 처리 시간이 긴 작업은 요청 즉시 `202 Accepted`로 응답하므로 이후 작업의 처리 상태를 조회하여 진행 상황과 결과를 확인해야 합니다. 작업의 처리 상태를 조회하는 방법은 각 서비스의 API 가이드를 참조해 주십시오.
- 조회 대상이 존재하지 않는 경우, 오류로 처리하지 않기 때문에 다음과 같이 응답합니다.
  - 단건 조회: 400 (조회 대상 없음)
  - 목록 조회: 200 (빈 목록 반환)

### 클라이언트 오류

클라이언트 오류로 인해 호출이 실패한 경우의 상태 코드는 다음과 같습니다. 메시지를 확인하여 사용자 조치 후 다시 시도해 주십시오.

| HTTP 상태 코드 | 메시지 | 설명 |
| --- | --- | --- |
| `400 BadRequest` | The request is malformed or contains an error such as an invalid parameter value or a missing required parameter. | 요청 형식이 올바르지 않거나 필수 파라미터 누락, 유효하지 않은 파라미터 값 등 요청 내용에 오류가 있는 경우 |
| `400 CannotDelete` | The delete operation could not be completed. | 기본 라우팅 테이블과 같이 정책상 삭제할 수 없는 자원에 대해 삭제를 요청한 경우 |
| `400 IdempotentParameterMismatch` | You have specified a client token for an operation using parameter values that differ from a previous request that used the same client token. | 동일한 클라이언트 토큰을 이전 요청과 다른 파라미터 값으로 다시 사용한 경우 |
| `400 IllegalArgument` | An argument in the request is not supported. | 요청에 지원하지 않는 인수가 포함된 경우 |
| `400 InvalidConfiguration` | Some or all of the configuration is incomplete, missing, or not valid. | 요청한 구성 정보의 일부 또는 전체가 누락되었거나 유효하지 않은 경우 |
| `400 InvalidNextToken` | You have provided an invalid pagination token in your request. | 목록 조회 요청에 유효하지 않은 페이지네이션 토큰이 포함된 경우 |
| `400 InvalidOperation` | The specified operation is invalid. | 요청한 작업이 유효하지 않거나 지원되지 않는 경우 |
| `400 InvalidParameter` | The specified parameter is invalid. | 요청 파라미터의 값이나 형식이 유효하지 않은 경우 |
| `400 InvalidState` | The specified state is not valid for the event source. | 요청한 작업을 수행할 수 없는 자원 상태이거나 유효하지 않은 상태값이 지정된 경우 |
| `400 InvalidTag` | The specified tag is invalid. | 태그의 키, 값 또는 형식이 유효하지 않은 경우 |
| `400 InvalidToken` | The token you provided is stale or isn't valid for the operation. | 요청에 사용한 토큰이 유효하지 않거나 해당 작업에 사용할 수 없는 경우 |
| `400 ResourceLimitExceeded` | The request exceeds the resource limit. | 자원에 설정된 허용 한도를 초과한 요청인 경우 |
| `400 TagLimitExceeded` | The maximum allowed number of tags was exceeded. | 자원에 등록할 수 있는 최대 태그 개수를 초과한 경우 |
| `401 ExpiredToken` | The token issued by the service has expired and is no longer valid. | 서비스에서 발급한 인증 토큰의 유효 기간이 만료된 경우 |
| `401 Unauthorized` | Invalid authentication credentials. | 인증 정보가 없거나 유효하지 않아 요청자를 인증할 수 없는 경우 |
| `403 AccessDenied` | The client is permanently forbidden from making the request. | 클라이언트에 해당 요청을 수행할 권한이 없어 접근이 거부된 경우 |
| `403 Forbidden` | You do not have sufficient permissions to perform this action. | 요청한 작업을 수행하는 데 필요한 권한이 부족한 경우 |
| `404 NotFound` | One or more of the resources in the request do not exist in the system. | 요청에 포함된 하나 이상의 자원을 찾을 수 없는 경우 |
| `404 ResourceNotFound` | The specified resource could not be found. | 요청에서 지정한 자원을 찾을 수 없는 경우 |
| `405 MethodNotAllowed` | The HTTP method used is not allowed for this resource. | 해당 자원에서 지원하지 않는 HTTP 메서드로 요청한 경우 |
| `406 NotAcceptable` | The server cannot produce a response matching the list of acceptable values defined in the request headers. | 요청 헤더의 응답 형식 조건을 서버가 충족할 수 없는 경우 |
| `408 RequestTimeout` | The request timed out. | 서버가 정해진 시간 내에 요청 처리를 완료하지 못한 경우 |
| `409 AlreadyExists` | A resource with the requested name already exists. | 동일한 이름 또는 식별 조건을 가진 자원이 이미 존재하는 경우 |
| `409 ConcurrentAccess` | Multiple operations can't be performed on the same tag simultaneously. Perform the operations sequentially. | 동일한 태그에 대해 여러 작업을 동시에 수행하여 충돌이 발생한 경우 |
| `409 Conflict` | The request could not be processed because of a conflict in the current status of the resource. | 자원의 현재 상태와 요청한 작업이 충돌하여 요청을 처리할 수 없는 경우 |
| `409 ResourceInUse` | The specified resource is in use. | 삭제 또는 변경 가능한 자원이 다른 자원이나 작업에서 사용 중인 경우 |
| `409 ResourceNotReady` | The resource is not ready. | 자원이 요청한 작업을 수행할 수 있는 준비 상태가 아닌 경우 |
| `412 PreconditionFailed` | The precondition in one or more of the request fields evaluated to false. | 요청에 지정한 하나 이상의 사전 조건을 충족하지 못한 경우 |
| `413 ContentTooLarge` | The request content exceeds the maximum allowed size. | 요청 본문의 크기가 허용된 최대 크기를 초과한 경우 |
| `415 UnsupportedMediaType` | The content type of the request body is not supported. | 요청 본문의 Content-Type을 서버에서 지원하지 않는 경우 |
| `424 DependencyFailed` | There was an issue with a dependency. Check the resource configurations and retry the request. | 요청 처리에 필요한 의존 자원의 구성 또는 상태 문제로 작업을 완료하지 못한 경우 |
| `429 RateLimitExceeded` | The request exceeded the rate limit. Retry after the specified time period. | 일정 시간 동안 허용된 API 요청 횟수를 초과한 경우 |
| `429 ResourceQuotaExceeded` | The allowed quota for the resource has been exceeded. | 특정 자원에 할당된 사용 한도를 초과한 경우 |
| `429 ServiceQuotaExceeded` | The request exceeds a service quota. | 서비스에 할당된 사용 한도를 초과한 경우 |
| `429 ThrottlingExceeded` | The request was denied due to request throttling. | 요청량 제어 정책에 따라 요청 처리가 제한된 경우 |
| `429 TooManyRequests` | The operation failed because it was called too frequently and exceeded a throttle limit. | 짧은 시간에 동일 작업을 과도하게 호출하여 요청 제한을 초과한 경우 |

### 서버 오류

서버 오류로 인해 호출이 실패한 경우의 상태 코드는 다음과 같습니다. 메시지를 확인하여 관리자 또는 네이버 클라우드 플랫폼에 문의해 주십시오.

| HTTP 상태 코드 | 메시지 | 설명 |
| --- | --- | --- |
| `500 InternalServerError` | The request processing has failed because of an unknown error, exception, or failure. | 서버 내부의 알 수 없는 오류 또는 예외로 요청 처리에 실패한 경우 |
| `502 BadGateway` | There was an issue with a dependency due to a server issue. Retry your request. | 게이트웨이 또는 프록시가 내부 연동 서버에서 정상적인 응답을 받지 못한 경우 |
| `503 InsufficientCapacity` | There is insufficient capacity to perform the action. | 서버 또는 인프라의 가용 용량이 부족하여 요청한 작업을 수행할 수 없는 경우 |
| `503 ResourceUnavailable` | This resource is currently unavailable. | 지정한 자원을 현재 일시적으로 사용할 수 없는 경우 |
| `503 ServiceUnavailable` | The service is currently unavailable. | 서비스가 일시적으로 요청을 처리할 수 없는 경우 |
| `504 GatewayTimeout` | There was a temporary issue with the service. Retry your request. | 게이트웨이 또는 프록시가 내부 연동 서버로부터 정해진 시간 내에 응답을 받지 못한 경우 |

## 오류 응답 바디

호출이 실패한 경우의 응답 바디에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `error` | Object | Required | 호출 오류 정보 |
| `error.errorCode` | String | Required | 오류 코드 |
| `error.message` | String | Required | 오류 메시지 |
| `error.detail` | String | Optional | 오류에 대한 상세 설명 |
| `error.fieldErrors` | Array | Optional | 값이 유효하지 않은 입력 항목 목록: [fieldErrors](/docs/fieldErrors) |

### fieldErrors

`fieldErrors`에 대한 설명은 다음과 같습니다.

| 필드 | 타입 | 필수 여부 | 설명 |
| --- | --- | --- | --- |
| `field` | String | Required | 값이 유효하지 않은 필드의 이름 |
| `message` | String | Required | 해당 필드의 오류 메시지 |

참고

2개 이상의 리소스를 한 번에 처리하는 API에서 일부 항목의 처리에 실패한 경우, 일반 오류를 나타내는 `error` 대신 최상위 `failures`에 실패한 항목의 오류 정보를 반환합니다. 단, 일괄 조회는 하나라도 조회할 수 없으면 요청 전체가 실패합니다.

- `failures`의 상세 구조와 각 API에서 발생할 수 있는 오류는 해당 서비스의 API 가이드를 참조해 주십시오.

## 오류 응답 예시

호출이 실패한 경우의 예시는 다음과 같습니다.

- 기본 오류 응답

```
{
  "error": {
    "errorCode": "NotFound",
    "message": "One or more of the resources in the request do not exist in the system."
  }
}
```
- 입력값이 유효하지 않은 필드가 2개 이상인 경우: `fieldErrors`에 각 필드의 오류 정보 반환

```
{
  "error": {
    "errorCode": "InvalidParameter",
    "message": "The specified parameter is invalid.",
    "fieldErrors": [
      {
        "field": "name",
        "message": "Name must be at least 3 characters long"
      },
      {
        "field": "age",
        "message": "age is required"
      }
    ]
  }
}
```