{"record":{"id":"9b41eabf0d886c0e","repo":"signalapp/Signal-Server","slug":"return-response-status-499-build","errorCode":null,"errorMessage":"return Response.status(499).build();","messagePattern":"return Response\\.status\\(499\\)\\.build\\(\\);","errorType":"http","errorClass":"ObsoletePhoneNumberFormatException","httpStatus":499,"severity":"warning","filePath":"service/src/main/java/org/whispersystems/textsecuregcm/mappers/ObsoletePhoneNumberFormatExceptionMapper.java","lineNumber":16,"sourceCode":"package org.whispersystems.textsecuregcm.mappers;\n\nimport io.micrometer.core.instrument.Metrics;\nimport jakarta.ws.rs.core.Response;\nimport jakarta.ws.rs.ext.ExceptionMapper;\nimport org.whispersystems.textsecuregcm.metrics.MetricsUtil;\nimport org.whispersystems.textsecuregcm.util.ObsoletePhoneNumberFormatException;\n\npublic class ObsoletePhoneNumberFormatExceptionMapper implements ExceptionMapper<ObsoletePhoneNumberFormatException> {\n\n  private static final String COUNTER_NAME = MetricsUtil.name(ObsoletePhoneNumberFormatExceptionMapper.class, \"errors\");\n\n  @Override\n  public Response toResponse(final ObsoletePhoneNumberFormatException exception) {\n    Metrics.counter(COUNTER_NAME, \"regionCode\", exception.getRegionCode()).increment();\n    return Response.status(499).build();\n  }\n}\n","sourceCodeStart":1,"sourceCodeEnd":19,"githubUrl":"https://github.com/signalapp/Signal-Server/blob/100ab61c82627582c867d19e1c0561ba2781e927/service/src/main/java/org/whispersystems/textsecuregcm/mappers/ObsoletePhoneNumberFormatExceptionMapper.java#L1-L19","documentation":"The ObsoletePhoneNumberFormatExceptionMapper turns an ObsoletePhoneNumberFormatException into HTTP 499 (client-closed-request, Signal's reuse) and increments a per-region error counter. The exception indicates the request supplied a phone number in an obsolete/legacy format that this server no longer accepts (e.g. old national-format or deprecated e164 handling for certain regions).","triggerScenarios":"Any endpoint validating phone numbers receiving a number that parses to an obsolete format for its region code — legacy formatting the server has deliberately dropped support for.","commonSituations":"Old clients (pre-format-migration) still sending numbers without strict E.164 normalization; numbers from regions whose formatting rules changed; cached contact lists containing legacy-formatted numbers.","solutions":["Upgrade the client to a version that normalizes numbers to current E.164 format","Normalize/reformat the phone number (proper +country code, no spaces/dashes) before sending","Check the per-region metrics counter (regionCode tag) to identify which regions' clients need updating","If a legitimate regional format is rejected, update the server's number-parsing library/configuration"],"exampleFix":"// before\nString number = \"(415) 555-2671\";\napi.register(number);\n// after\nString number = PhoneNumberUtil.getInstance().format(raw, PhoneNumberFormat.E164); // +14155552671\napi.register(number);","handlingStrategy":"validation","validationCode":"// normalize to E.164 before any API call\nString e164 = PhoneNumberUtil.getInstance().format(\n    PhoneNumberUtil.getInstance().parse(rawNumber, defaultRegion), PhoneNumberFormat.E164);\nif (!e164.startsWith(\"+\")) throw new IllegalArgumentException(\"not E.164: \" + rawNumber);","typeGuard":"boolean isModernE164(String n) {\n  return n != null && n.matches(\"\\\\+[1-9]\\\\d{7,14}\");\n}","tryCatchPattern":"if (response.code() == 499) {\n  log.warn(\"obsolete phone format for region; upgrade client/normalize number\");\n  normalizeAndResend();\n}","preventionTips":["Always normalize numbers to E.164 before API calls","Keep the client's libphonenumber/regional formatting current","Watch the per-region 499 metrics to find outdated client populations","Scrub cached contacts of legacy formats"],"tags":["http","phone-number","deprecated-format","validation"],"backgroundTag":"deprecated-api-usage","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"}