Errors and limits
An error is an HTTP status code and JSON:
{ "error": "invalid", "message": "birth_year: members must be 18+" }Rely on error — the codes are stable. message is for people and logs; its text may change.
Error codes
| HTTP | error |
What it means | What to do |
|---|---|---|---|
| 400 | bad_json |
The body is not JSON | Check your serialization |
| 400 | bad_id |
A parameter is not a UUID (match_id, to, up_to) |
Pass ids from network responses as is |
| 401 | unauthorized |
Missing key, invalid key, or the platform’s environment is suspended | Check the Authorization: Bearer … header |
| 403 | forbidden |
The action is not allowed: liking or disliking your own user through the network; the member is hidden after reports or deleting their account (no feed either) | Don’t retry |
| 404 | not_found |
No such member, match or message — or it isn’t yours. also a like to someone your user can’t see: a block, the other environment, a hidden member | The user wasn’t sent to the network, was deleted or is unavailable: remove the card |
| 409 | match_closed |
The match is closed | Close the conversation on your side |
| 409 | matched |
The like already made a match — it can’t be undone | Don’t retry |
| 409 | location_change_limited |
The city was changed less than a day ago: a new city or a move over 50 km | Tell the person they can change the city in a day; send other changes with the previous city |
| 409 | match_frozen |
One of the two is deleting their account (can restore within 30 days) or was hidden by the network after reports | “Account deleted” or “Account unavailable”; messaging resumes after a restore or reinstate |
| 409 | member_hidden |
The member is hidden (consent.network: false): no feed; can only like back someone who liked them, no super likes |
Offer to rejoin the network |
| 409 | photo_check_gone |
Photo check page only: the gesture task expired or was already used | The page offers to start again by itself |
| 409 | world_consent_required |
scope=world feed for a member without the Worldwide consent |
Offer to turn Worldwide on; until then, the regular feed |
| 422 | invalid |
The data failed validation — the field is in message |
Fix the data; don’t retry as is |
| 429 | rate_limited |
More than 600 requests per minute | Wait and retry with a delay |
| 429 | super_like_limit |
More than 5 super likes a day | Tell the person super likes come back tomorrow; a regular like still works |
| 429 | photo_check_limit |
more than 10 photo checks for one person a day | Tell the person they can try again tomorrow |
| 429 | first_messages_limit |
A new member (first 7 days in the network) has already started 20 conversations today | Don’t retry; tell the person they can start new conversations tomorrow. Replies in existing ones are fine |
| 503 | photo_check_off |
the photo comparison service is temporarily unavailable | Retry later |
| 500, 503 | internal |
Network error or temporary unavailability (503 can come even on the key check — your key is fine) | Retry with exponential backoff |
Retries on your side
- Retryable: network errors, timeouts,
429 rate_limited,5xx. Delays: 1 s, 2 s, 4 s… up to a minute. - Safe to retry:
PUT /v1/members,PUT /v1/members/…,DELETE /v1/members/…,POST /v1/activity,POST /v1/likes,POST /v1/dislikes,POST /v1/blocks,POST /v1/matches/{id}/read— a retry won’t create duplicates. - Careful:
POST /v1/matches/{id}/messages— a retry after a timeout may send the message twice. Retry only if you are sure no response arrived, and show the user a “not sent” status.
Limits
| What | Value |
|---|---|
| Requests | 600 per minute per platform, bursts up to 100 |
| Request body | up to 1 MB |
| Feed | up to 50 profiles per request, up to 200 distinct people per member per day. Repeating a page does not spend the limit |
Profile batch (PUT /v1/members) |
up to 100 |
| Dislike batch | up to 100 |
Activity marks (POST /v1/activity) |
up to 1000 per request |
| Incoming likes | up to 100 per request |
Events (GET /v1/events) |
up to 500 per request, kept for 7 days |
| Message history | up to 100 per request |
| Message | 1–4000 characters |
| Profile bio | up to 1000 characters |
| Photos | 1–9 per profile |
external_id |
1–128 characters |
| City change | once a day |
| Super likes | 5 a day per member, message up to 200 characters |
| New conversations for new members | 20 a day during the first 7 days |
| Webhook delivery | 10-second timeout, retries for up to 3 days |
If the limits aren’t enough for you, write to us and we’ll raise them.
Optional services
See network services for entitlement_required (402), commerce_forbidden (403), commerce_conflict, quote_expired, boost_incompatible_with_incognito (409), invalid_commerce_request (422), commerce_unavailable and live_payments_unavailable (503). insufficient_test_credits (402) is TEST-only. Never replace an order reference after a timeout: retry the same request.