Skip to main content
The Orgo API returns errors as JSON. Which JSON depends on where the error was raised, so this page lists every envelope you can meet before it lists the status codes. Whatever the envelope, the HTTP status line is authoritative.

Error envelopes

A small, fixed set of shapes exist. Code that reads the HTTP status first and the body second handles all of them.

1. Request errors: title, detail, status

Malformed input that Orgo rejects before or while handling the request (invalid JSON, a bad page value, a missing required field, a duplicate create, a reference to something that no longer exists):

2. Framework errors: Problem JSON or Hydra

Errors raised by the API layer itself (an authorization refusal, a missing item, an unhandled fault) use the format you asked for. With Accept: application/json you get application/problem+json; with Accept: application/ld+json you get a Hydra error:
Servers running in debug mode add a trace array; do not rely on it.

3. Validation errors (422)

See the 422 entry below. They add a violations array to the framework envelope.

4. Sign-in errors: code, message

A missing, expired or invalid session JWT, and a refused password login, answer with:
Other messages in this family: Invalid JWT Token, Invalid credentials., and SSO_REQUIRED_<connection uuid> when the member’s email domain requires their identity provider.

5. Emailed-code and identity-provider refusals

The emailed-code and password-reset endpoints answer a required identity provider with 409 and {"error": "SSO_REQUIRED", "message": "...", "connection": "<uuid>"}. See Authentication.

6. OAuth token endpoint

RFC 6749 shaped: {"error": "invalid_grant", "error_description": "..."}. See Authentication.

7. Public event checkout

The public event registration endpoints (/api/v1/public/event/{uuid}/save-attendees, .../payment-intent, .../complete, .../complete-free) answer failures with {"error": "<message>"} and the matching status. See Build a public event landing page.

Status codes

The request is malformed or refers to something that cannot work: invalid JSON, a page that is not a positive integer, a missing required field, an unknown enum value, a business rule that refuses the action (“Already voted”, “ID document is missing”).
?page=0 is a 400. A page of 0, a negative number, or a value that is not a number is a client error and answers 400 with the detail above. It used to be a 500.Many faults that were once 500 now answer a proper 4xx with the cause in detail: a follow, mute or vouch with a missing target, creating a family or a widget without a name, sending or rescheduling a newsletter with an unparseable time, an unknown custom field visibility or waitlist priority, a product edited to a slug another product holds (422), an unknown website page status or menu location (422), and a custom action on an item that does not exist or belongs to another tenant (404).Retry? No. The same request will fail again. Read detail and fix it.
A session JWT or OAuth token is missing, malformed, expired or revoked. Revocation applies on the next request, so a token that still looks valid can be refused.
A bad Api-Token is not a 401: it answers 404 (see below).Retry? Yes, after signing in again or refreshing an OAuth token. If a fresh token still fails, the host might be wrong, see Tenancy.
You are authenticated, but the user (or the token) lacks the permission the action needs.Common reasons:
  • A read-only Api-Token sent a write: This API token has read-only access.
  • A scoped Api-Token reached outside its categories: This API token is not scoped for this resource.
  • A read-only OAuth app sent a POST, PUT, PATCH or DELETE.
  • The member manages people for one local center and the resource belongs to another.
  • The endpoint is for organization administrators and the caller is a chapter manager.
Retry? No. Have an administrator grant the missing permission, or use a different token.
The resource does not exist, or it exists in a different tenant than the one your request is scoped to. Orgo answers 404 (not 403) in the second case so a 404 never confirms that a record exists somewhere else.
Two surprises. An unknown, expired or revoked Api-Token answers 404 with No user associated with this API Token., not 401. And a custom action on an item that does not exist (POST /things/{id}/verb) answers 404, not 500.Retry? No. Verify the id, the URL, the token and the tenant host.
The request conflicts with the current state of the resource.
  • Duplicate: creating something whose identifier already exists, for example a contact whose email is already a contact or a member.
  • Optimistic locking: another writer updated the record between your read and your write. Refetch and retry.
  • Required identity provider: an emailed-code or password-reset call for an address whose domain must sign in through the organization’s provider (SSO_REQUIRED).
Retry? Sometimes. For optimistic-lock collisions: refetch, reconcile and retry once. For duplicates and SSO_REQUIRED: no.
The request is well-formed but one or more fields failed validation.
Iterate violations[] to show each message next to the right field. code is a stable validator identifier, useful if you localize messages yourself.Not every business rule is a field violation. Rules enforced in code (for example, a slug another product already holds) answer 422 or 400 with only detail.Retry? No. Correct the fields and resubmit.
You reached a limit on this endpoint. Which limits exist, and their sizes, are listed in Rate limits.Retry? Yes, after the Retry-After header (seconds). Wrong OAuth client secrets are throttled separately and a 429 there means your credentials are wrong.
Something went wrong inside Orgo. The detail may be generic to avoid leaking internals. A 500 on a request that sends bad input is a defect, not an expected answer: report it.Retry? Yes, with exponential backoff. If a 500 reproduces on the same call, contact support with the time and the request.
The gateway or an upstream dependency is unreachable.Retry? Yes, with exponential backoff (start around 1 second, double up to around 30 seconds, give up after around 5 minutes).

Retry strategy

A safe default for any integration:
Do not retry:
  • 400, 401, 403, 404, 422: retrying produces the same failure (a 401 is worth one retry after signing in again)
  • 409 from duplicates or SSO_REQUIRED: retrying still conflicts
  • 409 from optimistic locks: refetch first, then retry once (not in a tight loop)

Logging tips

Log the status, the detail (or message, or error, depending on the envelope) and the URL. The body’s status mirrors the HTTP status in the envelopes that have one, but the sign-in and public checkout envelopes do not, so keep the status line.
  • Authentication: what 401, 403 and 404 mean per auth method
  • Tenancy: why a 404 may actually be a tenant mismatch
  • Rate limits: how to avoid 429 in the first place