Errors

The Synex API uses conventional HTTP status codes and always returns the same error envelope, so you can branch on machine-readable fields rather than parsing prose. A 2xx means success; 4xx means the request needs fixing; 5xx means something failed on our side.

The error envelope

Every non-2xx response has a single top-level error object.

Name
type
Type
string
Description
Broad category — branch on this first. One of the types listed below.
Name
code
Type
string
Description
Specific, machine-readable failure — branch on this second.
Name
message
Type
string
Description
Human-readable explanation. Do not parse it; wording may change.
Name
param
Type
string
Description
The offending request parameter, when applicable. Nullable.
Name
request_id
Type
string
Description
Echo of the X-Request-Id header. Quote it when contacting support. Nullable.
Name
errors
Type
object
Description
Per-field details on validation failures (for example, property id → messages).

Example error

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "Passport not found.",
    "param": "passport",
    "request_id": "req_9f2c1ab34d5e6f70"
  }
}

Error types

Name
invalid_request_error
Type
400/404/405/409/422
Description
Bad parameters, missing resources, or state conflicts.
Name
authentication_error
Type
401
Description
Missing or invalid key, or revoked team membership.
Name
permission_error
Type
403
Description
The key lacks the required ability, ontology scope, or team role.
Name
rate_limit_error
Type
429
Description
Too many requests — honor the Retry-After header.
Name
idempotency_error
Type
409
Description
An idempotency key was reused with a different payload, or is still in flight.
Name
api_error
Type
5xx
Description
Something failed on our side. Retry with backoff.

Common codes

Name
resource_missing
Type
code
Description
The id doesn't exist in your team — resources in other teams read as missing.
Name
parameter_invalid
Type
code
Description
A request field failed validation; param and errors say which.
Name
value_invalid
Type
code
Description
A passport property value was rejected; errors maps property id → messages.
Name
template_not_draft
Type
code
Description
Completed templates are immutable; only drafts can be edited or deleted.
Name
template_is_draft
Type
code
Description
Drafts can't be forked or instantiated — complete the template first.
Name
passport_exists_at_level
Type
code
Description
A singular level already has a passport under that parent.
Name
friendly_id_taken
Type
code
Description
The friendly id is already used within the parent.
Name
composition_missing / composition_exists
Type
code
Description
No composition exists yet · a composition already exists.
Name
ability_not_scoped_to_resource
Type
code
Description
The key's ontology scope doesn't cover this resource.
Name
lab_not_enabled
Type
code
Description
The team hasn't enabled Synex Lab.
Name
preview_mismatch
Type
code
Description
A transform preview expired or no longer matches the submitted AST.
Name
not_rollback_eligible
Type
code
Description
Only the latest completed, non-rolled-back transform can be rolled back.
Name
invalid_cursor
Type
code
Description
The pagination cursor is malformed or tampered with.

Handling guidance

Branch on type first, then code. Never parse message — it is meant for humans and its wording can change without a version bump.

4xx — fix the request; retrying it unchanged will fail again. The two exceptions are a 409 in-flight idempotency conflict and a 429.
429 — wait the number of seconds in Retry-After, then retry. See Rate limits.
5xx — retry with exponential backoff, reusing the same Idempotency-Key so a write can't be duplicated.