OpenCode Free limit reached 해결: 기다릴지 전환할지 판단하기

OpenCode에 Free limit reached 또는 HTTP 429가 표시됐다고 해서 모든 무료 model이 매일 같은 시각에 reset된다고 가정하면 안 됩니다. 먼저 원본 error를 보존하고 현재 provider와 model을 확인한 뒤, 이번 response나 account에 실제로 표시된 reset 안내만 판단 근거로 사용하세요.

신뢰할 수 있는 시간이 없다면 기다리거나, /models에 현재 표시되는 다른 model을 선택하거나, 별도로 과금되는 provider로 명시적으로 전환할 수 있습니다. 긴 coding task를 다시 시작하기 전에 file을 수정하지 않는 작은 request를 보내고 response, 선택된 provider/model, provider 측 usage를 확인해야 합니다.

증상에 맞는 분기부터 선택하기

표시 내용	가능성이 높은 원인	첫 조치
Free limit reached 또는 FreeUsageLimitError, countdown 없음	무료 사용량 limit	고정 주기를 추측하지 말고 시각을 기록한 뒤 기다리거나 /models의 현재 사용 가능 model을 확인
Go limit reached와 실제 countdown	OpenCode Go 유료 usage window	해당 account에 표시된 시간만 따르고 무료 model에 적용하지 않기
일반 429, Too Many Requests, Provider is overloaded	provider rate limit, 용량 부족, 일시 장애	전체 response를 저장하고 provider/model 확인 후 나중에 재시도하며 provider status 확인
401, 404, Model not available	인증, Base URL, Model ID 문제	reset을 기다리지 말고 credential, endpoint, model config 수정

같은 HTTP status라도 원인은 다를 수 있습니다. 429는 무료 quota 소진뿐 아니라 일반 provider 제한이나 일시적인 overload에서도 발생하므로, status code 하나만 보고 plan을 구매하거나 config를 전부 바꾸지 마세요.

전환하기 전에 네 가지를 저장하기

1. “429”만이 아닌 전체 error text.
2. 선택된 provider와 model, 가능하면 providerId/modelId 형식.
3. Client가 실제로 보여 주는 response body, error type, headers, retry-after.
4. 실패 시각과 time zone, project directory, 무료 Zen·Go·custom provider 중 어떤 경로였는지.

OpenCode Zen 문서에 따라 TUI에서 /models를 실행해 현재 선택된 entry와 지금 목록에 있는 model을 확인하세요. Terminal에서는 opencode models를 실행할 수 있습니다. 오래된 screenshot이나 guide에 있다는 이유만으로 특정 무료 model이 아직 제공된다고 판단하면 안 됩니다.

Config 우선순위도 확인해야 합니다. OpenCode config 문서에 따르면 OpenCode는 여러 config source를 merge하며 project-level opencode.json이 global setting을 override할 수 있습니다. Global에서 model A를 골랐다는 사실만으로 현재 repository가 model A를 사용한다고 볼 수 없습니다. 현재 project, /models 선택, resolved config를 기준으로 판단하세요.

실제로 표시된 reset만 신뢰하기

현재 error에 신뢰할 수 있는 countdown이나 절대 시각이 없다면 “몇 시간 뒤”, “내일”, “다음 주”라고 추측하지 마세요.

이 글을 위해 2026-10-10에 열어 확인한 OpenCode dev branch의 retry.ts snapshot에서는 FreeUsageLimitError가 정적인 무료 limit 안내 branch로 들어갑니다. 반면 GoUsageLimitError는 response header의 retry-after를 읽어 countdown을 만듭니다. 이는 source-code snapshot 검토이지, 사용자의 installed version이나 account를 실행해 측정한 결과가 아닙니다.

공개 feature request #53252와 #52894에는 정확한 reset 시간 예시가 있지만, 이는 요청한 기능을 설명하기 위한 sample일 뿐 실제 무료 tier schedule이 아닙니다. Issue가 closed 상태라고 해도 사용 중인 client version에 적용됐다는 증거는 아닙니다.

2026-10-10에 연 OpenCode Go 공식 문서는 유료 usage에 대해 5-hour, weekly, monthly window를 별도로 정의합니다. 이 Go 규칙을 무료 model reset 주기로 확장해서는 안 됩니다.

다음 원칙을 사용하세요.

• countdown 또는 정확한 시각이 표시됨: 원문, time zone, provider를 저장하고 해당 시각 근처에서 한 번 재시도합니다.
• 시각이 표시되지 않음: reset 시각을 unknown으로 취급하고 빠른 반복 retry나 다른 plan window로 대체하지 않습니다.
• 일반 429만 표시됨: 무료 limit이라는 증거가 나올 때까지 provider throttling 또는 overload를 조사합니다.

선택 1: 같은 무료 model이 필요하면 기다리기

Task가 급하지 않고 별도 API usage를 원하지 않으며 error가 무료 tier를 명확히 가리킬 때 가장 단순한 선택입니다.

1. 마지막 실패 시각과 raw error를 기록합니다.
2. Quota 문제와 일시 rate limit을 섞지 않도록 연속 retry를 중지합니다.
3. 신뢰할 수 있는 timer가 있으면 해당 시각 근처에서 시도합니다. Timer가 없으면 감당할 수 있는 간격으로 확인하되 고정 주기라고 말하지 않습니다.
4. 많은 file을 읽거나 수정하는 task가 아니라 짧은 request로 먼저 검증합니다.

성공은 OpenCode가 실행되거나 process exit code가 0인 상태가 아닙니다. 선택한 model이 실제 response를 반환하고 원래 error가 즉시 반복되지 않아야 합니다.

선택 2: /models에 현재 있는 다른 model 선택하기

작업을 계속해야 하지만 원래 model이 필수는 아니라면, account에 지금 보이며 의도한 provider에서 접근 가능한 다른 entry를 선택합니다.

전환 전에 다음을 확인하세요.

• Model이 오래된 tutorial이 아니라 현재 list에 존재하는가.
• Entry가 예상한 provider에 속해 model 변경이 모르는 사이 account나 billing 변경이 되지 않는가.
• Model이 task에 적합한가. Repository 수정을 허용하기 전에 짧은 code 이해 또는 tool use request로 확인합니다.

Model 변경은 성공을 보장하지 않습니다. 다른 무료 model도 자체 limit, 지역 제한, 임시 제거, capacity 문제를 가질 수 있습니다. 올바른 지침은 “현재 사용 가능한 model을 선택해 검증하라”이지 “무료 model을 바꾸면 항상 복구된다”가 아닙니다.

선택 3: 별도 과금 provider를 명시적으로 사용하기

Deadline이 있고 별도 API usage를 허용하며 이후 request를 Zen 무료 quota와 분리하려면 이 경로를 사용합니다. 이는 무료 quota reset이 아닙니다. 이후 call이 다른 account, API Key, usage record를 통해 처리됩니다.

OpenCode provider 문서는 custom OpenAI-compatible provider를 지원합니다. 최소 흐름은 다음과 같습니다.

1. /connect를 실행하고 Other를 선택해 고유 provider ID를 입력한 뒤 credential field에 API Key를 저장합니다.
2. opencode.json에 같은 provider ID, 올바른 Base URL, 실제 Model ID를 설정하고 file을 저장합니다.
3. 새 설정을 확인하기 전에 OpenCode를 완전히 종료한 뒤 같은 project에서 다시 시작합니다. 이미 열린 TUI가 새 provider를 hot reload한다고 가정하지 마세요. 이전 task context가 필요하면 project directory와 돌아갈 task 또는 session을 기록하고, 재시작 후 현재 환경에서 지원하는 workflow로 안전하게 돌아갑니다.
4. 재시작 후 /models를 실행해 새 entry가 표시되는지 확인하고, 표시 이름만 보지 말고 정확한 providerId/modelId를 선택합니다.
5. File을 수정하지 말라고 명시한 작은 request를 보내 실제 새 model response를 확인합니다.
6. 대상 provider의 request log, usage record 또는 balance change를 확인해 실제로 해당 request가 처리되었는지 검증합니다. 대응 기록이 없다면 전환이 검증됐다고 말하지 마세요.

BetterToken은 이 독립 경로에서 선택할 수 있는 provider 중 하나입니다. 2026-10-10에 연 BetterToken OpenCode 설정 문서는 Base URL https://www.bettertoken.ai/v1과 bettertoken/YOUR_MODEL_ID 같은 model reference를 안내합니다. Base URL에 /chat/completions를 붙이지 말고 top-level model이 models의 실제 ID와 정확히 일치하는지 확인하세요.

경계는 분명합니다. BetterToken은 Zen 무료 quota를 제공하거나 OpenCode/Zen limit을 reset하지 않습니다. 모든 429를 피한다고 보장할 수도 없고 동일 usage 비교 없이 자동으로 더 저렴하다고 말할 수도 없습니다. 이는 별도의 명시적인 API route이지 무료 quota 복구 기능이 아닙니다.

작은 request로 실제 복구 여부 확인하기

기다림, model 변경, provider 변경 모두 같은 acceptance test를 사용합니다.

1. Interface에서 선택된 provider/model을 다시 확인합니다.
2. File을 수정하지 않고 단어 READY만 반환하라고 요청합니다.
3. Response와 시각을 저장하고 config 승인 메시지나 cached output이 아니라 새 model response인지 확인합니다.
4. 독립 provider라면 usage record, request log, balance에 대응하는 작은 변화가 있는지 확인합니다. Provider가 그런 증거를 제공하지 않으면 billing까지 검증했다고 말하지 않습니다.
5. 원래 error가 다시 나오지 않으면 실제 task로 돌아가 가장 작은 의미 있는 step부터 실행합니다.

유효한 PASS에는 실제 response, 예상한 provider/model, provider 측 usage evidence가 함께 필요합니다. Config parse 성공, client 실행, 정상 exit code만으로는 충분하지 않습니다.

작은 request도 실패할 때

모든 수정을 반복하지 말고 새 error branch를 따라가세요.

• 같은 Free limit reached: quota가 아직 돌아오지 않았거나 선택이 실제로 바뀌지 않았을 수 있습니다. /models와 project config를 다시 확인합니다.
• 401: 해당 provider credential이 있는지 확인합니다. opencode auth list를 실행하고 필요하면 /connect를 다시 합니다.
• 404 또는 Model not available: Base URL, Model ID, providerId/modelId를 확인하고 opencode models로 현재 access를 봅니다.
• 일반 429 또는 overload: provider throttling으로 처리하고 retry 빈도를 낮추며 status를 확인합니다. 계속 Zen 무료 limit으로 간주하지 마세요.
• Error가 불완전함: OpenCode troubleshooting guide에서 log를 확인하고 시각, provider, model, status, secret을 제거한 response body와 함께 보고합니다.

API Key를 issue, screenshot, chat에 붙여 넣지 마세요. 필요한 error 정보는 남기되 Authorization headers, token, credential은 제거합니다.

자주 묻는 질문

OpenCode 무료 quota는 매일 같은 시각에 reset되나요?

모든 무료 model이 하나의 daily, weekly, monthly cycle을 공유한다는 신뢰할 만한 1차 근거는 없습니다. 현재 request에 표시된 시간만 사용하고, 없으면 unknown으로 취급하세요.

모든 429가 무료 quota 소진을 뜻하나요?

아닙니다. 일반 provider rate limit, concurrency limit, overload일 수도 있습니다. provider, model, response body, error type을 함께 봐야 합니다.

OpenCode Go 구독만이 유일한 방법인가요?

아닙니다. 기다리거나 현재 사용 가능한 다른 model을 선택하거나 독립 provider를 명시적으로 사용할 수 있습니다. Go는 별도 유료 plan이며 그 window는 무료 model reset의 증거가 아닙니다.

BetterToken으로 바꾸면 무료 limit이 사라지나요?

아닙니다. 자체 API Key, Base URL, Model ID, usage accounting을 가진 독립 provider route입니다. Zen 무료 quota 상태는 바뀌지 않습니다.

실전 결론

Free limit reached를 reset 주기 추측으로 해결하지 마세요. 실제 provider/model을 식별하고 표시된 reset만 신뢰하며, deadline에 따라 기다림, /models의 현재 사용 가능 model, 별도 과금 provider 중 가장 덜 disruptive한 경로를 선택하세요. 원래 task로 돌아가기 전에 짧은 response와 provider 측 usage로 복구를 입증해야 합니다.