API error reference

The short answer

Every error the SealDeal API returns is `application/problem+json` following RFC 7807, and its `type` field is a link to the page describing exactly that error. If you landed here from a `type` URL in a response, the page you want is linked below under the matching status code. Each one states what the error means, what causes it, and, the part most error references leave out, whether retrying the same request can ever succeed.

The shape of an error

Read `detail` first: it is specific to your request and usually names the exact field, scope or count that caused the failure. `type` is stable and safe to switch on in code; `title` and `detail` are human-facing and may be reworded.

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json

{
  "type": "https://sealdeal.ai/errors/insufficient-scope",
  "title": "Insufficient scope",
  "status": 403,
  "detail": "The API key is missing required scopes: contacts.write."
}

Authentication

The request could not be attributed to a valid key, or to a person behind that key.

401 Missing API key
The request arrived with no Authorization header at all.
/errors/missing-authorization · Retry only after changing the request
401 Invalid API key
The key presented does not resolve to a live key. A malformed key and an unknown-but-well-formed key both return this identical response, deliberately, so the API cannot be used to probe which key prefixes exist.
/errors/invalid-api-key · Retry only after changing the request
401 API key expired
The key was valid but has passed its expiry date.
/errors/expired-api-key · Retry only after changing the request
401 API key has no actor
The key is valid but is not linked to an active team member, so any write it performed could not be attributed to a person.
/errors/api-key-no-actor · Retry only after changing the request

Authorization

The key is valid, but either the token lacks a scope or the person behind it lacks a role. Both must permit the operation.

403 Insufficient scope
The key is valid but was not granted a scope this endpoint requires. The `detail` field names exactly which scopes are missing.
/errors/insufficient-scope · Retry only after changing the request
403 Forbidden
The key had the right scope, but the acting team member is not allowed to perform this operation on this resource.
/errors/forbidden · Retrying will not help
403 Erasure requires an org admin
GDPR erasure is restricted by ROLE as well as by scope, and the acting member does not hold a qualifying role.
/errors/erasure-forbidden · Retrying will not help
403 Outbound not included
The organization's plan does not include outbound sending.
/errors/outbound-not-entitled · Retry only after changing the request
403 Pre-sales not included
The organization's plan does not include the pre-sales module, so the questionnaire endpoints are closed to it.
/errors/presales-not-entitled · Retry only after changing the request
403 API access needs a paid plan
The workspace plan does not include the API, so the key was refused.
/errors/api-access-paid-plans · Retry only after changing the request
403 Webhooks need a paid plan
The workspace plan does not include webhooks, so the request was refused.
/errors/webhooks-paid-plans · Retry only after changing the request

Request and state

The call was understood but cannot be performed as sent, or against the resource in its current state.

404 Not found
No resource with that id exists inside your organization. The API never distinguishes a missing record from one belonging to another tenant.
/errors/not-found · Retrying will not help
400 Bad request
The request body or query was malformed or failed validation. `detail` says which field.
/errors/bad-request · Retry only after changing the request
405 Method not allowed
The path exists, but it does not accept this HTTP method. The `Allow` response header lists the methods it does accept.
/errors/method-not-allowed · Retrying will not help
415 Unsupported media type
The request carried a body that is not JSON. Every request body this API accepts is JSON; a JSON body is read whatever Content-Type it was sent with.
/errors/unsupported-media-type · Retry only after changing the request
409 Conflict
The resource exists and you may touch it, but its current state does not permit this operation.
/errors/conflict · Retry only after changing the request
422 Idempotency key reused
An Idempotency-Key you already used on this endpoint was sent again with a different request body, so the request cannot be a replay of the first.
/errors/idempotency-key-reused · Retry only after changing the request
409 List has in-flight sequences
Deleting this list would strand sequences that are mid-cadence: the list disappears while its prospects keep receiving later steps.
/errors/list-has-in-flight-sequences · Retry only after changing the request
422 Stage gate not met
The deal cannot advance because your organization's qualification methodology has an unmet exit condition on the current stage.
/errors/stage-gate-blocked · Retry only after changing the request
422 Deal has no primary contact
The activity could not be logged because the deal has no primary contact to anchor it to. Every activity row is attached to a person as well as a deal.
/errors/deal-has-no-contact · Retry only after changing the request
422 Contact is excluded
The contact is never researched because it is on your own company's domain or at a company on your organization's exclusion list. Nothing ran and no action was charged.
/errors/contact-excluded · Retry only after changing the request
402 No actions left
The workspace has no actions left, so this draft run (or questionnaire answering run) was not started.
/errors/actions-exhausted · Retry only after changing the request
402 Draft allowance exhausted
A rewrite would write a new draft, and the organization's draft allowance (its plan's emails, or the free trial) is used up, or Outbound is not active for it. Nothing was generated.
/errors/draft-allowance-exhausted · Retry only after changing the request

Limits

Different 429s. They mean different things and need different handling.

429 Rate limit exceeded
The key exceeded its plan's requests per 60 seconds (Starter 60, Team 120, Growth 300, Scale 600, Enterprise 1,200; the X-RateLimit-Limit header names yours). The limit applies to every endpoint.
/errors/rate-limit-exceeded · Safe to retry after a backoff
429 Organization rate limit exceeded
The organization's combined limit was reached across its API keys: all its keys together get twice the per-key limit per 60 seconds (Growth: 300 per key, 600 across every key). Every key in the organization is refused until the window resets, even one that has made no requests.
/errors/organization-rate-limit-exceeded · Safe to retry after a backoff
429 Research budget exceeded
The organization hit its daily cap on new research runs. This is a different 429 from the request rate limit.
/errors/research-budget-exceeded · Safe to retry after a backoff
429 Research queue full
The organization already has the maximum number of queued asynchronous research jobs (25). A queued job runs within a few minutes; the cap stops one burst from holding the shared research queue.
/errors/research-queue-full · Safe to retry after a backoff

Server

Nothing the client sent is wrong.

503 Erasure is not configured
The server cannot write a tamper-resistant suppression tombstone, so it refuses to erase rather than erase weakly.
/errors/erasure-unavailable · Retry only after changing the request
503 File storage not configured
This deployment has no file storage configured, so a questionnaire file cannot be uploaded or an answered file exported.
/errors/storage-not-configured · Retry only after changing the request
502 Regeneration failed
The model run behind a rewrite failed, so no new version was written and the draft is exactly as it was.
/errors/generation-failed · Safe to retry after a backoff
500 Internal error
Something failed server-side. The response carries a stable error code and no internal detail.
/errors/internal-error · Safe to retry after a backoff