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

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
• 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
• 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

Limits

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

• 429 Rate limit exceeded
  The key exceeded 60 requests per 60 seconds. The limit applies to every endpoint.
  /errors/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

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
• 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