Errors
Problem details (RFC 9457) with stable error codes and hints for agents.
Errors use Content-Type: application/problem+json:
{
"type": "https://resolido.com/docs/api/errors#scope_missing",
"status": 403,
"code": "scope_missing",
"message": "This token is missing the conversations:reply scope.",
"hint": "Create a key with the Inbox or Full access preset in Settings → Developers.",
"request_id": "req_7f69893354fd418c9937feac63aba553"
}codeis stable – branch on it, not onmessage.hinttells a person or an agent what to do next.- Some codes add fields, e.g.
summaryandconfirmation_tokenfor confirmations orretry_after_secondsfor rate limits. - Retry only
429and5xxresponses, with backoff. Everything else needs a different request.
The CLI maps errors to exit codes; the SDK throws ResolidoError.
Authentication and permissions
unauthorized
401. The token is missing, malformed, expired or revoked. Refresh an OAuth token or create a new API key.
forbidden
403. The resource belongs to a different organization than the token, or your role does not allow the action.
scope_missing
403. The token lacks a scope the operation needs, or it is read-only. The hint names the missing scope.
Request problems
validation_failed
400 / 422. A parameter or body field is missing or invalid. The errors array lists each problem with its path and message.
invalid_json
400. The body is not valid JSON or not a JSON object.
invalid_cursor
422. The pagination cursor is malformed or belongs to another query. Start again without cursor.
not_found
404. No resource with this id exists in your organization. Use an id returned by a list or search operation.
route_not_found
404. No such endpoint. Operations live under /v1; check the reference.
Safeguards
confirmation_required
409. A destructive operation needs explicit confirmation, or the confirmation token is invalid or expired. See Confirmations.
idempotency_key_required
400. Customer-facing operations need an Idempotency-Key header. See Idempotency.
invalid_idempotency_key
400. The key must be 8–128 characters of letters, digits and _ . : -.
idempotency_in_progress
409. A request with the same key is still running. Retry in a few seconds.
idempotency_mismatch
422. The key was already used with a different request. Use a new key for a new request.
rate_limited
429. Too many requests. Wait for Retry-After seconds. See Rate limits.
Operation errors
conflict
409. The resource is in a state that does not allow the action – for example the customer wrote again since you prepared a reply (ifLastCustomerMessageId).
edit_conflict
422. A find-and-replace edit (agents_prompt_edit, skills_text_edit) did not match exactly once, or an agent changed since expectedUpdatedAt. Nothing was changed; problems lists each edit with not_found, ambiguous or stale.
action_skill
409. skills_test_saved only runs lookup skills. Action skills (refill, restart, refund…) run through skills_run_action, which asks for confirmation.
not_in_trash
409. Only conversations in trash can be deleted permanently. Move it to trash first.
no_mailbox
409. The agent has no connected mailbox for this email action.
action_failed
422. The action could not be completed; the message says why.
skill_test_failed
422. The skill's HTTP endpoint returned an error or an unexpected response during a test.
invalid_test_session
422. The test conversation does not exist or belongs to another agent. Start a new test without testSessionId.
file_download_failed, file_too_large, unsupported_file_type
422. A knowledge file URL could not be downloaded, is over 10 MB, or is not a supported type (pdf, doc, docx, txt, csv, md, json).
invalid_image
422. The avatar is not a valid image.
contact_not_blockable
422. This contact cannot be blocked (for example it has no identifier on the channel).
upstream_failed
502. An external service (email provider, WhatsApp, a website) failed. Retry later.
internal_error
500. Something went wrong on our side. Retry with backoff; if it persists, contact support with the request_id.