Errors

An error answers with an HTTP status and a JSON body that names a stable code:

{"error": "invalid", "details": {"name": ["has already been taken"]}}

error is always there; read it, not the wording. details appears only for some codes. Its messages are written for people: show them to the admin, do not parse them.

Every code

Status error Meaning What to do
400 bad_request The body is not valid JSON, or a required parameter is missing (then details.missing names it). Fix the request. Send Content-Type: application/json with a valid, flat JSON body.
401 invalid_token The key is missing, mistyped, expired or revoked, or its admin is no longer an owner or admin of the community. The answer is the same for every cause, with the header WWW-Authenticate: Bearer realm="Zen Social", error="invalid_token". Check the Authorization: Bearer … header. If it is right, stop and ask the admin for a new key. See Keys and access.
403 forbidden The key works, but its admin could not do this in the app, for example change a circle they are not an owner or admin of. Ask the admin to join that circle in the app (as its owner or admin, if it is to be changed). Do not look for a way around it.
404 not_found It does not exist, or it belongs to another community. Check the id. A key never reaches outside its community.
409 record_deleted A create's external_id belongs to something that was imported and has been deleted since. It is never brought back. Skip it and report it to the admin. Do not delete or retry.
409 changed_since_import A create's external_id belongs to something that someone changed in the app after your last write. It was not overwritten. Skip it and report it to the admin. Do not delete or retry.
409 conflict Two requests made the same thing at the same moment, for example two creates with one external_id. Send the request again, once, after the other one has answered.
422 invalid A value is not allowed. details names each field and why, for example {"accessibility": ["is not included in the list"]} or {"photo": ["could not be fetched as an image"]}. Nothing was saved. Fix the value. When it is a choice for the admin (a name that is taken), ask them.
422 confirmation_required A circle delete without confirm, or with a confirm that is not the circle's slug. Nothing was deleted. Only after the admin's clear yes: send the circle's slug as confirm. See Circles.
422 multiple_owners A circle delete for a circle that does not have exactly one owner. Nothing was deleted. Tell the admin. The circle's owners sort it out in the app first.
429 (see below) Too many requests. Wait the seconds in Retry-After, then go on, one request at a time.

Too many requests: 429

At most 300 requests a minute per key, and 600 a minute from one network address. Above that the answer has the header Retry-After: 60 and a body without a stable code:

{"error":"Too many requests. Please try again later."}

Wait that many seconds before the next request.

An address that does not exist

A path the API does not have, such as /posts in this version, answers 404 with a web page, not JSON. Check the path against these pages.

Server errors: 500

Something went wrong on Zen Social's side. Stop, tell the admin what you were doing, and try again later. If a create fails like this, sending it again with the same external_id is safe.