{"record":{"id":"f2297a2cbe9bf19d","repo":"signalapp/Signal-Server","slug":"503-service-unavailable","errorCode":null,"errorMessage":"503 Service Unavailable","messagePattern":"503 Service Unavailable","errorType":"http","errorClass":"ServerErrorException","httpStatus":503,"severity":"error","filePath":"service/src/main/java/org/whispersystems/textsecuregcm/controllers/VerificationController.java","lineNumber":482,"sourceCode":"              Optional.of(updateVerificationSessionRequest.captcha()), sourceHost, userAgent)\n          .orElseThrow(() -> new ServerErrorException(Response.Status.INTERNAL_SERVER_ERROR));\n\n      Metrics.counter(CAPTCHA_ATTEMPT_COUNTER_NAME, Tags.of(\n              Tag.of(SUCCESS_TAG_NAME, String.valueOf(assessmentResult.isValid(captchaScoreThreshold))),\n              UserAgentTagUtil.getPlatformTag(userAgent),\n              Tag.of(COUNTRY_CODE_TAG_NAME, Util.getCountryCode(registrationServiceSession.number())),\n              Tag.of(REGION_CODE_TAG_NAME, Util.getRegion(registrationServiceSession.number())),\n              Tag.of(SCORE_TAG_NAME, assessmentResult.getScoreString())))\n          .increment();\n\n      CaptchaMetrics.measureCaptchaOutcome(assessmentResult.getNormalizedIntScore(),\n          assessmentResult.isValid(captchaScoreThreshold),\n          Util.getRegion(registrationServiceSession.number()),\n          \"verification\");\n\n    } catch (final IOException e) {\n      logger.error(\"error assessing captcha during registration verification\", e);\n      throw new ServerErrorException(Response.Status.SERVICE_UNAVAILABLE, e);\n    } catch (InvalidCaptchaArgumentException e) {\n      throw new BadRequestException(e);\n    }\n\n    if (assessmentResult.isValid(captchaScoreThreshold)) {\n      final List<VerificationSession.Information> submittedInformation = new ArrayList<>(\n          verificationSession.submittedInformation());\n      submittedInformation.add(VerificationSession.Information.CAPTCHA);\n\n      final List<VerificationSession.Information> requestedInformation = new ArrayList<>(\n          verificationSession.requestedInformation());\n      // a captcha satisfies a push challenge, in case of push deliverability issues\n      requestedInformation.remove(VerificationSession.Information.PUSH_CHALLENGE);\n      final boolean allowedToRequestCode = (verificationSession.allowedToRequestCode()\n          || requestedInformation.remove(VerificationSession.Information.CAPTCHA))\n          && requestedInformation.isEmpty();\n\n      verificationSession = new VerificationSession(verificationSession.sessionId(),","sourceCodeStart":464,"sourceCodeEnd":500,"githubUrl":"https://github.com/signalapp/Signal-Server/blob/100ab61c82627582c867d19e1c0561ba2781e927/service/src/main/java/org/whispersystems/textsecuregcm/controllers/VerificationController.java#L464-L500","documentation":"handleCaptcha wraps an IOException from the captcha assessment call (to the captcha provider, e.g. reCAPTCHA Enterprise) in a ServerErrorException with HTTP 503 SERVICE UNAVAILABLE. This means the server could not reach or get an answer from the captcha service, so verification cannot proceed at this moment. It is a transient upstream availability problem, not a client mistake.","triggerScenarios":"updateSession with a captcha token while the call to the captcha assessment API throws IOException — network outage, DNS failure, TLS error, or the captcha provider returning an unreadable/unreachable response.","commonSituations":"Captcha provider outage or degraded network from the service host; egress firewall blocking the captcha API; expired/misconfigured service credentials causing connection resets; transient DNS failures in containerized environments.","solutions":["Retry the updateSession request after a short backoff — 503 here is typically transient.","Check service logs for 'error assessing captcha during registration verification' to see the underlying IOException cause.","Verify outbound network access and DNS from the service host to the captcha provider endpoint.","Confirm captcha provider credentials/endpoint configuration (captcha configuration in dynamic config) are valid and current."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { await updateSession(...); } catch (e) {\n  if (e.status === 503) { await sleep(backoff()); return updateSession(...); }\n  throw e;\n}","preventionTips":["Retry transient 503 with backoff","Monitor captcha provider status","Ensure egress connectivity to the captcha API","Keep provider credentials valid"],"tags":["http-503","captcha","upstream","network","io"],"backgroundTag":"upstream-api-error","analyzedSha":"100ab61c82627582c867d19e1c0561ba2781e927","analyzedAt":"2026-09-09T13:29:47.883Z","contentChangedAt":"2026-09-09T13:29:47.883Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}