한 줄 요약: 사용량 확인 화면에 다른 서비스 연동을 넣어 보았지만, 정상 동작을 반복해서 확인하기 전에는 완료나 리뷰로 올리지 않았습니다. 멈춘 기준과 어디까지 됐는지 적는 방법을 남깁니다.
연동보다 확인 가능한 상태가 먼저였습니다
한 화면에서 여러 서비스의 정보를 같이 보면 편할 것이라고 생각해서 연동을 넣어 보았습니다. 그런데 화면에 값이 보이는 것과 그 값이 지금 상태를 정확히 반영하는 것은 다른 문제였습니다.
값이 언제 갱신되는지, 오류가 났을 때 어떻게 처리하는지, 다시 실행했을 때 같은 결과가 나오는지가 모두 맞아야 실제로 쓸 수 있는 기능이라고 판단했습니다. 사용량처럼 숫자를 다루는 화면은 특히 그렇습니다. 숫자가 보이는 순간 사용자는 그 숫자를 믿고 다음 행동을 정하기 때문입니다.
그래서 연동을 붙이는 작업과 그 연동을 쓸 수 있다고 말하는 작업을 따로 나눴습니다. 앞의 작업은 코드를 쓰면 끝나지만, 뒤의 작업은 확인이 끝나야 끝납니다. 이 글은 뒤의 작업이 끝나지 않아 멈춘 기록입니다.
사용량 화면에서 틀리기 쉬운 지점은 크게 세 곳입니다. 첫째는 갱신 시점입니다. 값이 오래된 것인데 방금 읽은 것처럼 보일 수 있습니다. 둘째는 오류 처리입니다. 읽지 못한 값이 빈칸이나 0으로 그려지면 사용량이 없는 것처럼 읽힙니다. 셋째는 다시 실행했을 때의 일관성입니다. 같은 조건인데 결과가 달라지면 어느 값을 믿어야 할지 알 수 없습니다.
내가 중단한 네 가지 기준
기능을 공개하기 전에 네 가지를 통과해야 한다고 정했습니다.
- 재현: 같은 조건에서 같은 결과가 다시 나오는지 봅니다.
- 출처: 어떤 서비스의 어떤 상태를 읽은 값인지 구분합니다.
- 오류: 값이 비어 있는 상황과 실제 오류를 같은 결과로 취급하지 않습니다.
- 실사용: 내가 반복해서 확인한 범위 안에서만 사용 중이라고 적습니다.
이 중 하나라도 빠지면 화면이 그럴듯해 보여도 공개 가능한 기능이라고 부르지 않기로 했습니다. 특히 한 번만 보인 결과는 기능이 동작한다는 증거가 아니라 한 번 관찰했다는 기록에 가깝다고 판단했습니다.
네 가지는 서로 다른 질문에 답합니다. 재현은 우연이 아닌지, 출처는 무엇의 값인지, 오류는 이상이 생겼을 때 어떻게 되는지, 실사용은 어디까지 말해도 되는지를 가려 줍니다. 하나가 빠지면 그 질문만 답이 없는 채로 남습니다.
기준마다 글에 적는 문장도 달라집니다. 아래는 예시입니다.
- 재현이 안 된 경우: 한 번 관찰된 결과라고만 적고 기능이라고 쓰지 않습니다.
- 출처가 불분명한 경우: 어느 서비스의 값인지 밝히지 못했다고 적습니다.
- 오류와 빈 값을 구분하지 못한 경우: 구분 기준이 아직 없다고 적습니다.
- 반복 사용을 못 한 경우: 사용 중이라고 쓰지 않고 시도해 본 범위만 적습니다.
어느 단계에서 멈췄는지 적는 법
미완료라고만 쓰면 독자도, 나중의 나도 무엇을 다시 해야 하는지 알 수 없습니다. 안 된다는 말보다 어디까지 됐다는 말이 훨씬 쓸모가 있습니다. 그래서 검증을 단계로 나누어 두었습니다.
| 단계 | 통과했을 때 말할 수 있는 것 | 아직 말할 수 없는 것 |
|---|---|---|
| 1. 인증 | 상대 서비스가 나를 알아봅니다. | 데이터를 받을 수 있는지 |
| 2. 수신 | 데이터를 한 번이라도 받았습니다. | 받은 값이 맞는지, 또 받을 수 있는지 |
| 3. 표시 | 받은 데이터를 화면에 그렸습니다. | 오류와 빈 값을 구분하는지 |
| 4. 유지 | 다시 시작한 뒤에도 같은 모습이 나옵니다. | 장기간 쓸 수 있는지 |
이 표는 제가 멈춘 지점을 적기 위해 만든 것입니다. 이렇게 나누면 나중에 다시 붙일 때 멈춘 지점부터 시작할 수 있습니다. 처음부터 다시 하지 않아도 된다는 점이 가장 큰 이득입니다.
단계마다 글에 쓸 수 있는 문장도 정해집니다. 1단계까지 통과했다면 인증까지 된다고만 씁니다. 2단계까지라면 데이터를 한 번 받았다고 씁니다. 3단계까지라면 화면에 표시된다고 씁니다. 4단계까지 통과해야 비로소 다시 실행해도 유지된다고 쓸 수 있습니다.
이 규칙은 글을 쓰는 사람이 스스로 과장하지 않도록 막는 장치이기도 합니다. 3단계까지 간 기능을 두고 완성됐다고 쓰는 일은 흔한데, 단계표가 있으면 그 말을 쓸 수 없게 됩니다.
빈 값과 오류를 같은 결과로 보면 생기는 일
네 가지 기준 중 오류 항목은 설명이 더 필요합니다. 서비스가 정상적으로 응답했는데 값이 비어 있는 경우와 서비스가 오류를 돌려준 경우는 의미가 전혀 다릅니다. 둘 다 화면에 빈칸이나 0으로 그리면 사용자는 사용량이 0이라고 읽습니다. 실제로는 읽지 못한 것인데도 말입니다.
공식 문서를 보면 오류를 구분해서 처리할 수 있게 응답이 설계되어 있습니다. Claude API 문서는 오류를 400, 401, 403, 404, 413, 429, 500, 529 같은 HTTP 상태 번호와 오류 종류로 나누어 알려 줍니다. 예를 들어 401은 API 키에 문제가 있을 때, 429는 사용 한도에 걸렸을 때, 500은 서비스 내부 오류일 때입니다. 모든 응답에는 요청 번호가 함께 들어 있어서, 문의할 때 그 번호를 같이 보내라고 안내합니다.
범용 규칙으로는 MDN의 상태 코드 설명이 있습니다. 401은 인증이 안 된 요청, 403은 서버가 신원은 알지만 접근 권한이 없는 요청, 429는 일정 시간 안에 요청을 너무 많이 보낸 경우, 503은 점검이나 과부하로 일시적으로 처리할 수 없는 상태입니다.
| 상태 번호 | 의미(공식 문서 기준) | 사용량 화면에서의 표시 제안 |
|---|---|---|
| 401 | 인증 문제 | 키 또는 로그인 확인이 필요하다고 표시 |
| 403 | 권한 없음 | 이 키로는 볼 수 없다고 표시 |
| 429 | 한도 초과 | 잠시 후 다시 시도한다고 표시 |
| 500, 529 | 서비스 내부 오류 또는 일시적 과부하 | 지금 읽지 못했다고 표시, 0으로 그리지 않음 |
마지막 열은 공식 문서의 내용이 아니라 이 글의 제안입니다. 어떤 경우든 읽지 못한 값을 0이나 이전 값으로 채워 넣지 않는 것이 핵심입니다.
미완료로 남기는 것도 결정입니다
기능을 넣지 못했을 때 선택지는 두 가지입니다. 되는 것처럼 보이게 만들거나, 미완료라고 적는 것입니다. 사용량처럼 숫자를 다루는 기능에서는 후자가 맞다고 생각합니다.
- 임의의 값을 채워 넣으면 사용자는 그 값을 믿고 판단합니다.
- 곧 지원한다는 표시는 언제까지인지 알 수 없어서 기다림만 만듭니다.
- 미완료라고 적으면 사용자가 다른 방법을 찾을 수 있습니다.
개발 기록에서 미완료는 실패한 결과를 숨기지 않는다는 표시입니다. 다음 작업에서 무엇을 다시 확인해야 하는지를 남기고, 독자에게도 아직 검증하지 않은 기능을 이미 쓰는 것처럼 오해하게 만들지 않기 위한 장치입니다.
앱이나 글에서 미완료를 표시할 때는 날짜가 없는 약속보다 현재 상태를 알려 주는 편이 낫습니다. 아래는 표기 예시입니다. 실제 서비스 화면이 아니라 설명을 위한 예시입니다.
| 표기 | 사용자가 받는 느낌 |
|---|---|
| 곧 지원합니다 | 언제인지 몰라 기다리게 됩니다. |
| 현재 지원 범위: 인증까지 | 어디까지 되는지 알고 판단할 수 있습니다. |
| 값 없음(임의 값으로 채우지 않음) | 빈 값이 정상 값이 아니라는 것을 압니다. |
공식 경로가 없을 때의 선택
연동하려는 서비스에 공식 API가 없는 경우에는 비공식 경로를 쓰지 않기로 했습니다. 웹페이지를 긁어 오거나 인증 토큰을 빼내는 방식은 당장은 동작할 수 있습니다. 그래도 세 가지 문제가 남습니다.
- 서비스 쪽이 조금만 바뀌어도 조용히 틀린 값을 냅니다. 오류가 아니라 틀린 숫자로 나타나니 알아채기 어렵습니다.
- 약관에 걸릴 수 있습니다.
- 사용자의 인증 정보를 다루게 되어 위험이 커집니다.
공식 경로가 없으면 그 연동은 넣지 않고 미완료로 남깁니다. 이 선택은 기능이 줄어드는 대신 틀린 숫자를 보여 줄 위험을 없애는 쪽을 고른 것입니다.
연동 전에 공식 경로가 있는지 가르는 질문은 세 가지입니다.
- 서비스가 공식 API 문서를 제공하는가?
- 그 문서가 내가 읽으려는 정보(사용량이나 상태)를 읽는 방법을 설명하는가?
- 인증은 문서가 안내하는 키 발급 방식을 따르는가?
공식 API는 문제가 생겼을 때 오류를 상태 번호와 오류 종류로 알려 줍니다. Claude API 문서에서도 키 문제는 401로, 권한 문제는 403으로 구분해서 돌려준다고 안내합니다. 그래서 오류가 났다는 사실을 화면에 그대로 드러낼 수 있습니다. 반대로 긁어 온 화면에는 이런 신호가 없어서, 틀려도 알려 주지 않습니다.
실패 기록을 남긴 이유와 이 글의 한계
기록을 남기는 목적은 두 가지입니다. 다음 작업에서 무엇을 다시 확인해야 하는지 알게 하는 것, 그리고 독자에게 아직 검증하지 않은 기능을 실제 사용 범위처럼 보이지 않게 하는 것입니다. 확인 범위가 넓어지면 새 기록으로 덧붙이되, 지금 글의 판단은 그대로 둡니다.
이 글은 계정 화면, 내부 설정, 원문 개발 문서, 실행 기록을 포함하지 않습니다. 공개 가능한 확인 기준과 제가 내린 판단만 적었습니다. 어떤 서비스를 연동했는지, 어느 단계에서 구체적으로 막혔는지는 공개 범위 밖이라 적지 않았습니다.
상태 번호와 오류 처리에 관한 설명은 공식 문서에서 가져온 일반 내용이고, 제가 실제로 어떤 번호를 받았는지는 이 글에 없습니다. 서비스의 응답 형식은 바뀔 수 있으니 연동하기 전에는 해당 서비스의 현재 문서를 먼저 읽으세요.
독자가 자기 프로젝트에 옮길 때는 세 가지만 기억하면 됩니다. 단계별로 어디까지 됐는지 적고, 읽지 못한 값은 0으로 채우지 않고, 공식 경로가 없으면 연동하지 않고 미완료로 남기는 것입니다.
사용량 화면처럼 숫자를 믿고 쓰는 기능은 틀린 값 하나가 잘못된 판단으로 이어집니다. 그래서 되는 것까지만 적고, 안 되는 부분은 안 된다고 적는 쪽이 장기적으로 신뢰를 지킨다고 봅니다.