Runtime API

Errors

Every error response is a JSON body with an error field. When something is actionable — pick an account, rename a parameter — the response also carries a details object.

Error envelope

Basic error

json

{
  "error": "Invalid request body"
}

With actionable details

json

{
  "error": "Capability \"linkedin_search_people\" requires connectedAccountId because it is available on multiple connected accounts",
  "details": {
    "availableAccounts": [
      { "connectedAccountId": "acc_1", "integrationId": "linkedin", "backend": "unipile" },
      { "connectedAccountId": "acc_2", "integrationId": "linkedin", "backend": "unipile" }
    ]
  }
}

Status codes

Copia keeps transport errors simple — HTTP status carries the class of failure, and the body carries the specifics.

200statusoptional
Request accepted; the runtime returned a successful JSON response.
400statusoptional
Invalid request body or malformed runtime input. Fix the payload and retry.
401statusoptional
Missing or invalid authentication — no key, or the key doesn't exist.
403statusoptional
The API key exists but does not include the required scope (runtime).
404statusoptional
Unknown session, execution, or capability for the current organization.
409statusoptional
The capability exists on multiple connected accounts and requires connectedAccountId. The body enumerates the available accounts.
500statusoptional
Unexpected runtime failure while invoking the capability. Safe to retry with backoff.

Retry policy

Idempotent capabilities (supportsIdempotency: true) are safe to retry on 5xx. For non-idempotent calls, check the event stream before retrying — the original run may still be in flight.

PreviousAPI reference NextOverview