# 에이전트 사람 전환 설정 교체 (/docs/api/agents/putAgentTransfer)
**PUT /v1/accounts/{accountId}/agents/{agentId}/transfer**
```json
{
  "operationId": "putAgentTransfer",
  "summary": "에이전트 사람 전환 설정 교체",
  "description": "전환 설정 전체를 교체합니다. 보내지 않은 항목은 기본값으로 돌아가므로 조회 응답을 고쳐서 보내세요.\n통화가 나갈 번호가 바뀌는 설정입니다. 변경은 다음 통화부터 적용됩니다.\n발신번호 범위를 지정한 API 키로는 호출할 수 없습니다.",
  "tags": [
    "Agents"
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "enabled",
            "targets"
          ],
          "properties": {
            "enabled": {
              "type": "boolean",
              "description": "사람 전환 사용 여부. 끄면 번호 형식과 안내 문구 내용은 검사하지 않습니다."
            },
            "targets": {
              "type": "array",
              "maxItems": 5,
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "label",
                  "number"
                ],
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "에이전트가 전환할 때 고르는 이름. 20자 이내이고 겹칠 수 없습니다.",
                    "example": "상담팀"
                  },
                  "number": {
                    "type": "string",
                    "description": "전환할 국내 번호",
                    "example": "010-1234-5678"
                  },
                  "weeklySchedule": {
                    "type": "object",
                    "required": [
                      "timezone",
                      "windows"
                    ],
                    "description": "이 대상의 주간 일정. 없으면 항상 전환할 수 있습니다.",
                    "properties": {
                      "timezone": {
                        "type": "string",
                        "enum": [
                          "Asia/Seoul"
                        ]
                      },
                      "windows": {
                        "type": "array",
                        "maxItems": 7,
                        "description": "요일별 구간. 요일당 하나입니다.",
                        "items": {
                          "type": "object",
                          "required": [
                            "day",
                            "start",
                            "end"
                          ],
                          "properties": {
                            "day": {
                              "type": "integer",
                              "minimum": 0,
                              "maximum": 6,
                              "description": "요일. 0이 월요일입니다.",
                              "example": 0
                            },
                            "start": {
                              "type": "string",
                              "description": "시작 시각(HH:MM)",
                              "example": "13:00"
                            },
                            "end": {
                              "type": "string",
                              "description": "종료 시각(HH:MM). 시작보다 뒤여야 합니다.",
                              "example": "18:00"
                            }
                          }
                        }
                      },
                      "excludedDates": {
                        "type": "array",
                        "maxItems": 366,
                        "description": "전환하지 않을 날짜(YYYY-MM-DD)",
                        "items": {
                          "type": "string",
                          "example": "2026-12-25"
                        }
                      }
                    }
                  }
                }
              }
            },
            "callerId": {
              "type": "string",
              "enum": [
                "account",
                "original"
              ],
              "description": "담당자 단말에 표시할 번호. 생략하면 `account` 입니다."
            },
            "whisper": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "enabled"
              ],
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "template": {
                  "type": "string",
                  "maxLength": 200,
                  "description": "안내 문구. `{발신번호}`, `{사유}` 를 쓸 수 있습니다. 생략하면 기본 문구입니다."
                }
              }
            },
            "timeout": {
              "type": "integer",
              "minimum": 10,
              "maximum": 60,
              "description": "담당자 응답 대기 시간(초). 생략하면 30입니다."
            },
            "holdMedia": {
              "type": "string",
              "enum": [
                "moh",
                "ringback",
                "silence"
              ],
              "description": "대기 중 발신자에게 들리는 소리. 생략하면 `moh` 입니다."
            },
            "onFailure": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "enabled"
              ],
              "properties": {
                "enabled": {
                  "type": "boolean"
                },
                "message": {
                  "type": "string",
                  "maxLength": 200,
                  "description": "연결되지 않았을 때 발신자에게 들려주는 안내"
                }
              }
            },
            "activeFrom": {
              "type": "string",
              "format": "date-time",
              "nullable": true,
              "description": "전환 허용 시작 시각. 오프셋을 포함해 `2026-11-04T09:00:00+09:00` 형식으로 보내고 `activeUntil` 과 함께 지정합니다."
            },
            "activeUntil": {
              "type": "string",
              "format": "date-time",
              "nullable": true
            }
          }
        },
        "example": {
          "enabled": true,
          "targets": [
            {
              "label": "상담팀",
              "number": "010-1234-5678"
            }
          ]
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "저장된 전환 설정",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "enabled",
              "targets",
              "callerId",
              "whisper",
              "timeout",
              "holdMedia",
              "onFailure",
              "activeFrom",
              "activeUntil"
            ],
            "properties": {
              "enabled": {
                "type": "boolean",
                "description": "사람 전환 사용 여부"
              },
              "targets": {
                "type": "array",
                "maxItems": 5,
                "items": {
                  "type": "object",
                  "required": [
                    "label",
                    "number"
                  ],
                  "properties": {
                    "label": {
                      "type": "string",
                      "description": "에이전트가 전환할 때 고르는 이름",
                      "example": "상담팀"
                    },
                    "number": {
                      "type": "string",
                      "description": "전환할 국내 번호",
                      "example": "01012345678"
                    },
                    "weeklySchedule": {
                      "type": "object",
                      "required": [
                        "timezone",
                        "windows"
                      ],
                      "description": "이 대상의 주간 일정. 없으면 항상 전환할 수 있습니다.",
                      "properties": {
                        "timezone": {
                          "type": "string",
                          "enum": [
                            "Asia/Seoul"
                          ]
                        },
                        "windows": {
                          "type": "array",
                          "maxItems": 7,
                          "description": "요일별 구간. 요일당 하나입니다.",
                          "items": {
                            "type": "object",
                            "required": [
                              "day",
                              "start",
                              "end"
                            ],
                            "properties": {
                              "day": {
                                "type": "integer",
                                "minimum": 0,
                                "maximum": 6,
                                "description": "요일. 0이 월요일입니다.",
                                "example": 0
                              },
                              "start": {
                                "type": "string",
                                "description": "시작 시각(HH:MM)",
                                "example": "13:00"
                              },
                              "end": {
                                "type": "string",
                                "description": "종료 시각(HH:MM). 시작보다 뒤여야 합니다.",
                                "example": "18:00"
                              }
                            }
                          }
                        },
                        "excludedDates": {
                          "type": "array",
                          "maxItems": 366,
                          "description": "전환하지 않을 날짜(YYYY-MM-DD)",
                          "items": {
                            "type": "string",
                            "example": "2026-12-25"
                          }
                        }
                      }
                    }
                  }
                }
              },
              "callerId": {
                "type": "string",
                "enum": [
                  "account",
                  "original"
                ],
                "description": "담당자 단말에 표시할 번호. `account` 는 계정 번호, `original` 은 걸려 온 전화의 발신자 번호입니다."
              },
              "whisper": {
                "type": "object",
                "required": [
                  "enabled",
                  "template"
                ],
                "description": "담당자가 받은 직후 담당자에게만 들려주는 안내",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "template": {
                    "type": "string",
                    "description": "안내 문구. `{발신번호}`, `{사유}` 를 쓸 수 있습니다.",
                    "example": "{발신번호} 고객님, {사유} 문의입니다"
                  }
                }
              },
              "timeout": {
                "type": "integer",
                "description": "담당자 응답 대기 시간(초)",
                "example": 30
              },
              "holdMedia": {
                "type": "string",
                "enum": [
                  "moh",
                  "ringback",
                  "silence"
                ],
                "description": "대기 중 발신자에게 들리는 소리"
              },
              "onFailure": {
                "type": "object",
                "required": [
                  "enabled",
                  "message"
                ],
                "description": "연결되지 않았을 때 발신자에게 들려주는 안내",
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "message": {
                    "type": "string",
                    "example": "지금은 상담원 연결이 어렵습니다."
                  }
                }
              },
              "activeFrom": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "전환 허용 시작 시각. `activeUntil` 과 함께 지정합니다."
              },
              "activeUntil": {
                "type": "string",
                "format": "date-time",
                "nullable": true,
                "description": "전환 허용 종료 시각"
              }
            }
          }
        }
      }
    },
    "400": {
      "description": "입력 오류 (VALIDATION)",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "인증 실패",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "403": {
      "description": "접근 권한 없음 또는 발신번호 범위를 지정한 API 키 (api_key_agent_transfer_restricted)",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "404": {
      "description": "에이전트를 찾을 수 없음 (AGENT_NOT_FOUND)",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    },
    "409": {
      "description": "저장된 설정을 읽을 수 없음 (AGENT_SPEC_INVALID)",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "properties": {
              "error": {
                "type": "string",
                "description": "사람이 읽을 수 있는 에러 메시지"
              },
              "code": {
                "type": "string",
                "description": "기계 판독용 에러 코드. **분기는 이 값으로 하세요** — `error` 문구는 안내를 다듬으면서\n바뀔 수 있지만 코드는 계약입니다.\n\n같은 상태 코드라도 대응이 갈리는 경우가 있습니다. 예를 들어 발신의 `422` 는\n  - `recipient_blocked`: 수신거부 명단에 있는 번호입니다. 재시도하지 말고 명단에서\n    해제해야 발신됩니다.\n  - `quota_exceeded`: 플랜 한도를 넘었습니다. 다음 주기에 다시 발신됩니다.\n\n전화번호 정규화 관련:\n  - `INVALID_PHONE_NUMBER`: 전화번호 포맷 오류 (한국 번호 형식 아님)\n  - `UNSUPPORTED_COUNTRY`: 국제 발신 미지원 (+82 외 국가코드)",
                "example": "recipient_blocked"
              },
              "ip": {
                "type": "string",
                "description": "`overseas_ip_blocked` 일 때만 옵니다. 국외 IP 라고 판정한 요청 IP 입니다.\n해외 리전 클라우드 서버에서 호출한다면 이 값이 그 서버의 공인 IP 이며, 콘솔\n「국외 접속 예외」에서 예외를 신청할 때 이 고정 IP 를 적습니다.",
                "example": "52.79.213.41"
              },
              "processedAt": {
                "type": "string",
                "format": "date-time",
                "description": "문자 발송 요청을 거부한 서버가 오류 응답을 생성한 시각(UTC). 콘솔은 이 값을 한국 시각으로 표시합니다. 인증·요청 형식 검증 등 발송 서비스 진입 전 오류에는 없을 수 있습니다.",
                "example": "2026-10-21T04:10:34.303Z"
              },
              "blockers": {
                "type": "array",
                "description": "`certificate_not_eligible` 일 때만 옵니다. 발급할 수 없는 번호와 그 이유입니다.",
                "items": {
                  "type": "object",
                  "description": "번호 하나가 발급되지 않는(또는 안내가 필요한) 이유.\n\n| code | 뜻 | 발급 |\n|---|---|---|\n| `number_not_owned` | 이 계정이 보유한 번호가 아님(반납·재배정 포함) | 막힘 |\n| `number_not_carrier_issued` | 한국AI통신이 개통한 070·대표번호가 아님(모바일 게이트웨이, 타사 번호) | 막힘 |\n| `business_info_incomplete` | 사업자 계정인데(관리번호 제외) 상호·사업자등록번호·대표자명·사업장 주소 중 빈 칸 | 막힘 |\n| `identity_unverified` | 개인 계정 번호 또는 관리번호인데 그 번호에 본인확인 정보가 없음 | 막힘 |\n| `account_restricted` | 이용 제한 계정 | 막힘 |\n| `business_recheck_pending` | 사업자 계정인데 사업자 정보 재확인이 진행 중(통과 전) — 관리번호를 뺀 계정의 모든 번호 | 막힘 |\n| `holder_is_personal` | 개인 명의로 찍힌다는 안내 | 가능 |",
                  "properties": {
                    "number": {
                      "type": "string",
                      "description": "422 응답의 blockers 에만 있다",
                      "example": "07012340002"
                    },
                    "code": {
                      "type": "string",
                      "enum": [
                        "number_not_owned",
                        "number_not_carrier_issued",
                        "business_info_incomplete",
                        "identity_unverified",
                        "account_restricted",
                        "business_recheck_pending",
                        "holder_is_personal"
                      ],
                      "example": "number_not_carrier_issued"
                    },
                    "message": {
                      "type": "string",
                      "example": "이용증명원은 한국AI통신이 개통한 070·대표번호만 발급됩니다."
                    }
                  },
                  "required": [
                    "code",
                    "message"
                  ]
                }
              }
            }
          }
        }
      }
    }
  }
}
```