OSS GroupMe app
group-me-not docs errors.md
5.0 kB · 106 lines
Markdown
at main

Errors and status codes #

The envelope #

{ "meta": { "code": 40901, "errors": ["Phone number already registered"] } }

meta.code is a five-digit code whose first three digits usually mirror the HTTP status. 40901 arrives on an HTTP 409, 42901 on a 429, 20001 on a 200 or 201.

The rule is a convention, not a guarantee: the 450xx family arrives on HTTP 403. Read the HTTP status from the status line and treat meta.code as the specific reason.

That structure means a client can branch on meta.code alone and derive the HTTP class from it. It also means a 2xxxx code is not an error: several endpoints use meta.code to communicate an outcome on an otherwise successful response.

meta.errors is an array of human-readable strings. It is not stable enough to branch on, though the app does exactly that in a few places. RegistrationViewModel string-matches the first error string to disambiguate 40003: startsWith("password") means the password was rejected, contains("email") means the email is taken, and anything else is treated as the phone number already being registered.

Codes recovered from the client #

Everything below is a code the app explicitly branches on. This is not the server's full vocabulary, only the part the Android client handles.

Success-with-meaning (2xxxx) #

Used by the group-join and event-join flows to report resulting membership state.

Code Meaning
20000 joined, membership active
20001 join requested, membership requested_pending
20100 joined, membership active (created)
20101 join requested, membership requested_pending (created)
20110 no membership resulted
20200 verification challenge issued; response.verification carries the details

Client errors (4xxxx) #

Code HTTP Meaning
40002 400 missing password
40003 400 identifier taken (email or phone), disambiguated by the error string
40004 400 invalid registration
40006 400 missing email
40081 400 assistant group is at max size
40101 401 invalid verification token
40121 401 account banned. Not retryable
40301–40303 403 call forbidden
40602 406 PIN verification took too long
40690 406 GDPR / age gate; response carries a verification.code to continue with
40901 409 phone number already registered, or locked
40902 409 phone number change conflict
41202 412 poll precondition failed
42901 429 rate limited
45018, 45019 403 assistant DM not allowed
45020–45022 403 assistant unavailable in this country
45030–45032 403 assistant blocked by age or location

Bare HTTP statuses the client treats specially #

Status Where Behavior
401 + meta.errors[0] == "unauthorized" any authenticated request five in a row logs the user out, but only when Content-Type is JSON or text (conventions)
403 GDPR check same handling as 40690
409 message send duplicate source_guid; treated as success
422 message send rejected, "links not allowed"
429 read-receipt sync schedules unread_batch_sync_429_retry with a 1-hour initial delay and 1-hour exponential backoff
201 login success
202 login accepted but incomplete; MFA challenge follows

What to retry #

The sync engine's list is the closest thing to an official answer in the binary:

retryableCodes = {408, 500, 502, 503, 504};   // plus errorCode < 0, i.e. transport failures

That is the ECS-supplied default and the server can override it, so do not treat it as a constant. Notably absent: 429. With the default set, a rate-limited sync fails outright rather than backing off, even though the read-receipt worker elsewhere handles 429 correctly. If you are rebuilding, put 429 in the retry set.

Never retry 400, 401, 403, 422, or any 4xxxx that describes a permanent state. 409 on a send is not a retry case either. It means you already succeeded.

Rate limiting #

Rate limits are real and reachable: registration, friend suggestions, group joins, the emoji picker, recaps, and read-receipt sync all have explicit 429 branches.

The server does send Retry-After on at least some 429s. JoinGroupRequest reads it case-insensitively from both allHeaders and headers, converts it to hours, and shows either "try again tomorrow" or "try again in N hours". RecapTriggerResponse carries a retryAfterSeconds field in the body for the same purpose.

Successful responses carry no X-RateLimit-* and no Retry-After (verified), so you cannot see your budget in advance. Read Retry-After when a 429 arrives, and fall back to exponential backoff with jitter when it is absent.