Errors

Every error body has the same three fields.

{
  "error": {
    "code": "invalid_limit",
    "message": "limit must be between 1 and 200",
    "retryable": false
  }
}

code is for your program. It does not change.
message is for a reader. It is written to be relayed to an owner.
retryable says whether the same request can succeed later.

Read retryable rather than guess from the status. A 502 from the hosting backend can be either.

The one extra field

A failed build carries a fourth field, detail, with the build log.

That log is the compiler telling whoever wrote the source what is wrong with it. detail is for build logs and nothing else.

Status and next action

A resource that is not finished the moment you ask for it carries two more fields of its own:

status, which says where it is;
next_action, in plain language, which says what to do now.

Relay next_action to the owner. It is written for that.

Codes you meet often

Code	Means
`not_found`	no such thing, or none you may see
`invalid_json`	the body is not valid JSON for this endpoint
`body_too_large`	the body is over 1 MiB
`invalid_cursor`	use `next_cursor` from an earlier answer
`provider_error`	the hosting backend refused or failed
`internal`	a fault on Clave's side; retry

Nothing provider-shaped leaks

No /v1 answer names the hosting provider, its identifiers or its error strings. A provider_error says the hosting backend refused and stops there.

Two answers carry a provider's address on purpose, because a payer's browser has to land on it: a checkout URL and a portal URL.

A message does not blame the wrong party

Clave works to keep each message about the party that can act on it. A refusal names the consequence and the remedy for the surface you are on.

If a message sends you to fix something you did not break, that is a defect here. Send it with POST /v1/feedback.