Errors

For AI agents: the docs index is at /llms.txt, and every page is also served as markdown at its URL plus .md.

The error envelope the service uses, its fields, and the codes a seller can see.

View as Markdown llms.txt for agents Full docs as text Docs sitemap

Every error from the service and the API uses this envelope.

Envelope

json

{
  "error": {
    "code": "conflict",
    "message": "The resource is in a state that does not allow this action.",
    "fix": "Read the resource and check its state.",
    "docs_url": "https://trialvalid.com/docs/errors#conflict",
    "retryable": false,
    "request_id": "req_example"
  }
}

Branch on code. fix says what to change, and retryable says whether sending the same request again can work.

Codes

Code	HTTP	Retryable	Meaning
`unauthorized`	401	No	The API key is missing, malformed, revoked or unknown
`forbidden`	403	No	This key is not allowed to make this request
`invalid_input`	400	No	The request input is invalid
`not_found`	404	No	No such resource exists for this account
`conflict`	409	No	The resource is in a state that does not allow this action
`signature_invalid`	400	No	A webhook signature or connect state did not verify
`rate_limited`	429	Yes	Too many requests for this key. Wait for `Retry-After`
`provider_unavailable`	503	Depends	A vendor is unavailable or not configured. If `retryable` is false, retrying will not help
`internal_error`	500	Once	Retry once with backoff

Another account's resource looks exactly like a missing one, so not_found never reveals that a resource exists.