Reference
Errors and limits
Every error with its code, safe retries and what to do with a 429.
The format
All errors share the same shape, with their HTTP status. fields comes when a value fails: each field, its code and its message. code values never change; messages follow Accept-Language.
{ "error": { "code": "…", "message": "…", "fields": [{ "path": "…", "code": "…", "message": "…" }] } }code | HTTP | When |
|---|---|---|
unauthorized | 401 | No token, or an expired or invalid one |
forbidden | 403 | The token lacks that operation's scope |
connection_revoked | 403 | The operator withdrew access |
not_found | 404 | The centre, unit, photo or request isn't part of this connection |
idempotency_key_reused | 409 | The same Idempotency-Key with a different body |
facility_not_ready | 409 | Sizes, units, floor plan or photos for a centre you haven't sent yet |
payload_too_large | 413 | Over 5 MB of JSON, 2 MB per floor or 15 MB per photo |
unsupported_media_type | 415 | A photo that isn't JPEG, PNG or WebP |
invalid_facility, invalid_unit_types, invalid_units, invalid_floor_plan, invalid_photo | 422 | With fields: every failing field |
rate_limited | 429 | Too many requests, with Retry-After |
server_error | 500 | Our fault. Try again with the same Idempotency-Key |
Safe retries
Send Idempotency-Key (a UUID) on everything that changes something. With the same key and the same body, for 24 hours, the response is the same, with the Idempotent-Replayed: true header. With a different body, 409 idempotency_key_reused. That way you can safely repeat what you're not sure arrived.
Limits
10 requests per second per operator permission, with bursts of 50. Over that, 429 rate_limited with Retry-After (in seconds): wait that long and repeat the request with the same Idempotency-Key.
| What | Up to |
|---|---|
| A JSON body | 5 MB |
| A floor plan | 2 MB per floor, 10 floors |
| A photo | 15 MB; 20 per centre |
| Centres in the daily list | 2,000 |