Handle API errors

Every error the Salesfinity API returns is JSON. There is no HTML error page, no plain-text fallback, and no endpoint that answers a failure differently — a client can parse a failure the same way on every route and every status code. The one exception is a request that never reaches the API, for example when the network edge in front of it cannot connect. That answer comes from the edge and may not be JSON. Treat a 5xx whose body does not parse as JSON as retryable, the same as any other 5xx.

The error envelope

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Field	Type	Description
`message`	string or string array	Human-readable description of what went wrong. Becomes an array of strings when request validation fails, with one entry per field that did not validate.
`error`	string	The HTTP reason phrase for the status, for example `Forbidden`, `Not Found`, `Bad Request`. Stable across releases — branch on this. One exception: a Sequencer write acting as a member with no active plan or seat gets `NO_ACTIVE_PLAN` here (see 403).
`statusCode`	integer	The HTTP status code, repeated in the body so it survives proxies and transports that drop it.
`request_id`	string	Identifies the request in Salesfinity’s logs. The same value as the `X-Request-Id` response header. Include it when you contact support.

Branch on error or statusCode, never on message. Message text is written for humans and may be reworded; error and statusCode are contractual.

Request IDs

Every response, successful or not, carries an X-Request-Id header, and every error body repeats it as request_id. To follow a request through your own logs and ours, send your own X-Request-Id: 1 to 128 characters of letters, digits, ., _, : and -. Salesfinity uses it as the request’s ID. If you send none, or one that does not fit that format, Salesfinity generates a UUID.

The order checks run in

A request is checked in this order, and the first check that fails decides the response. When a request could fail in more than one way, this tells you which error you will see.

The body is read. A body that is not valid JSON gets 400; one over the size limit gets 413.
The route is matched. A method and path that match no route get 404 Cannot <METHOD> <path>.
The API key is checked. A missing or unknown key gets 403.
The rate limit is counted. Over the limit gets 429. Every request that got this far counts, whatever happens next.
The Idempotency-Key is claimed, on Sequencer writes that send one. A reused or busy key gets 409.
Parameters and body are validated. Anything that does not match the schema gets 400 with one message entry per problem. GET /v1/call-log, GET /v1/scored-calls, GET /v1/contact-lists/csv and GET /v1/contact-lists/csv/{id} are the exception for unknown query parameters: they drop one rather than refuse it.
The operation runs. It can still answer 400, 402, 403, 404, 409, 422 or a 5xx, as its reference page says.

Status codes

400 Bad Request

The request is malformed. Most often a parameter or body field failed validation, and message is an array with one entry per invalid field. A field the operation does not define is a validation failure too, except in the query of the four list endpoints named in step 6 above, which ignore what they do not recognize.

{
  "message": [
    "linkedin_url must be a linkedin.com/in/<username> URL",
    "type must be one of the following values: work, personal",
    "property phone should not exist"
  ],
  "error": "Bad Request",
  "statusCode": 400,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

message is a single string when the request fails before validation or in the operation itself: a body that is not valid JSON, an ID in the path that is not a valid ID, or a rule such as a user_id that is not on the team. Not every route checks the ID first; the ones that do not are listed under 500.

{
  "message": "Invalid ObjectId format for parameter: id",
  "error": "Bad Request",
  "statusCode": 400,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Recover by reading message and correcting what it names. Check the request against the schema shown on the operation’s reference page. Retrying an identical request will fail identically.

402 Payment Required

The team has run out of enrichment credits. Only the requests that start an enrichment return this; reading a result or the balance never does.

{
  "message": "Insufficient enrichment credits. Please top up to continue.",
  "error": "Payment Required",
  "statusCode": 402,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

These are the team’s enrichment credits, which the API and the MCP server spend. They are separate from the SmartEnrich credits members spend in the dialer, and they cannot be bought in the dashboard. Recover by asking Salesfinity to add team enrichment credits, then retrying. Call Get enrichment credit balance before a bulk run to avoid hitting this mid-batch.

403 Forbidden

The x-api-key header is missing, malformed, revoked, or belongs to a different team.

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Salesfinity returns 403 for authentication failures, not 401. A client written around the usual “re-authenticate on 401” convention will never trigger its auth-recovery path against this API. Handle 403 explicitly.

Recover by checking that the x-api-key header is present and spelled correctly, that the key has not been revoked in Settings → Connections & API, and that it belongs to the team whose data you are requesting. A 403 with any message other than Forbidden resource is not about the key. It means the team member you are acting as, the user_id, may not do this. For example, a Sequencer write acting as an inactive member gets The acting user is not an active member of this team, and editing someone else’s note gets Only the author can edit this note. Act as a member who is allowed to. A Sequencer write acting as a member who has no active plan or seat is refused before anything else is checked, and its error is NO_ACTIVE_PLAN instead of Forbidden:

{
  "statusCode": 403,
  "error": "NO_ACTIVE_PLAN",
  "message": "An active plan or seat is required to use this feature. Please upgrade your plan or ask your team admin to assign you a seat.",
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Assign that member a seat, or act as one who has one.

404 Not Found

Either the route does not exist, or the resource does exist but belongs to another team.

{
  "message": "Cannot GET /v1/unknown-route",
  "error": "Not Found",
  "statusCode": 404,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

A message of the form Cannot <METHOD> <path> means the route itself is wrong — check the method and path against the reference. Any other message means the route was correct but the record was not found for this team. Recover by verifying the path, the HTTP method, and any ID in the URL. Because API keys are team-scoped, the API returns 404 rather than 403 for records owned by another team; it does not confirm that they exist.

409 Conflict

The request conflicts with an earlier request or with the current state of the record. The most common cause is an Idempotency-Key that was already used. See Retrying writes safely.

{
  "message": "This Idempotency-Key was already used with a different request body.",
  "error": "Conflict",
  "statusCode": 409,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Recover by working out which case you hit:

The key was already used for a different request, with another body or another path. Send a new key. Reusing a key for a different request is a bug in the client.
The first request with this key is still running. The message is A request with this Idempotency-Key is still in progress. Wait a moment, then retry with the same key. Once the first request has finished, the retry returns its response.
The record’s state rules the action out, for example completing a manual_email task whose send is already in flight, or reordering steps while people are mid-cadence. The operation’s reference page says when this applies. An identical retry fails the same way until the state changes.

413 Payload Too Large

The body is over the size limit: 10 MB on /v1/contact-lists and /v2/sequencer, 1 MB on every other route. The request was not processed.

{
  "message": "request entity too large",
  "error": "Payload Too Large",
  "statusCode": 413,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Recover by splitting the request. For enrolling many people, an enrollment run takes up to 5,000 contacts in one request.

422 Unprocessable Entity

The Sequencer understood the request, but its rules refuse it. Examples: enabling a sequence that has no steps or no mailbox able to send, or adding contacts to a sequence that is archived, has no steps, or has enrollment paused. Contacts refused one by one, for example because they are suppressed or a rule blocks them, are not a 422: the bulk operations report them in their response.

{
  "message": "Sequence has no steps and cannot be enabled",
  "error": "Unprocessable Entity",
  "statusCode": 422,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Recover by fixing what message names, then sending the request again. An identical retry fails identically until then.

429 Too Many Requests

The team has used up a rate limit for the current minute. Limits are per team, so every API key on the team draws on the same budget. See Rate limits for the limits and the routes each one covers.

{
  "message": "Rate limit of 300 requests per minute exceeded. Retry in 12s.",
  "error": "Too Many Requests",
  "statusCode": 429,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Recover by waiting the number of seconds in the Retry-After response header, never more than 60, then retrying. The refused request did nothing, so retrying it is safe even for a write. To avoid the 429 in the first place, pace bulk jobs with the X-RateLimit-Remaining and X-RateLimit-Reset headers, which come on every response to an authenticated request. Because the budget is shared, a burst from one integration can throttle another integration on the same team.

500 Internal Server Error

Something failed on the Salesfinity side.

{
  "message": "Internal server error",
  "error": "Internal Server Error",
  "statusCode": 500,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Recover by retrying with exponential backoff. If it persists, email [email protected] with the request_id, the request path and the timestamp.

502 Bad Gateway and 504 Gateway Timeout

The Sequencer and enrichment endpoints pass requests on to a Salesfinity service behind the API. 502 means that service could not be reached. 504 means the Sequencer did not answer within 55 seconds.

{
  "message": "Sequencer service timed out",
  "error": "Gateway Timeout",
  "statusCode": 504,
  "request_id": "0f6d3c52-9f3e-4c1a-a4b8-2b1f7e5d9c10"
}

Recover by retrying with exponential backoff. After a 504 on a write, the write may still have finished, so confirm with a GET before retrying a create.

Other statuses

During planned maintenance, /v2/sequencer routes answer 405 with error Method Not Allowed and a message that says maintenance is in progress. Retry later. The first time a sequence with email steps is enabled, Salesfinity sets up email sending for the team. If that briefly fails, Enable a sequence answers 503 Service Unavailable; retry after a moment.

Which errors are retryable

Status	Retryable	Notes
400	No	The request is malformed; an identical retry fails identically
402	No	Requires more team enrichment credits first
403	No	Requires a valid key, or a `user_id` allowed to act
404	No	Requires a correct path or ID
405	Later	Sequencer maintenance; retry after a few minutes
409	Sometimes	Retry with the same `Idempotency-Key` if the first request is still running; otherwise fix the request or the record
413	No	Requires a smaller body
422	No	Requires fixing what `message` names
429	Yes	Wait for the seconds in `Retry-After`, then retry
500	Yes	Back off with exponential jitter
502, 504	Yes	Back off; confirm state before retrying a create
503	Yes	Retry after a moment

Retrying writes safely

Outside the Sequencer, POST endpoints are not idempotent: sending the same request twice acts twice. Cap retries on writes, and confirm state with a GET before retrying a create so you do not duplicate a record. Every POST /v2/sequencer/* endpoint except the three /preview endpoints accepts an Idempotency-Key header, which makes a retry safe. Generate a unique value, such as a UUID, for each write, and send the same value when you retry that write. PATCH, PUT and DELETE requests do not take one.

A retry with the same key and the same request returns the original successful response without acting again.
The same key with a different body or path returns 409. The comparison covers the method, the path including its query string, and the JSON body.
The same key while the first request is still running returns 409. Retry after a moment.
A request that fails frees its key, so the retry runs normally. That includes a 5xx: after a 500, 502 or 504 on a create, the work may have finished behind the error, so confirm with a GET before retrying.
Keys are kept for 24 hours and are scoped to your team.
A 429 is not a failure of the write: the request was refused before the key was claimed, so the retry is the first attempt.

curl -X POST https://client-api.salesfinity.co/v2/sequencer/tasks \
  -H 'x-api-key: YOUR_API_KEY' -H 'content-type: application/json' \
  -H 'Idempotency-Key: 5d0e2c4a-6f1b-4f7e-9a3c-8b2d1e0f7a64' \
  -d '{ "user_id": "USER_ID", "action": "call", "contact": "CONTACT_ID", "due_at": "DUE_AT" }'

Replace DUE_AT with an ISO 8601 time within the next 365 days, for example 2026-11-02T15:00:00Z.

Handling errors in code

async function salesfinity(path, init = {}) {
  const res = await fetch(`https://client-api.salesfinity.co${path}`, {
    ...init,
    headers: { "x-api-key": process.env.SALESFINITY_API_KEY, ...init.headers },
  });

  if (res.ok) return res.json();

  // Every API error is JSON with the same envelope. A failure at the network
  // edge may not be, so fall back to the status line.
  const body = await res.json().catch(() => ({}));
  const statusCode = body.statusCode ?? res.status;
  const error = body.error ?? res.statusText;
  const request_id = body.request_id ?? res.headers.get("x-request-id");
  const detail = Array.isArray(body.message) ? body.message.join("; ") : body.message;

  const err = new Error(`Salesfinity ${statusCode} ${error}: ${detail} (request ${request_id})`);
  err.statusCode = statusCode;
  err.requestId = request_id;
  err.retryable = statusCode === 429 || statusCode >= 500;
  // On a 429, the number of seconds to wait before retrying.
  err.retryAfter = Number(res.headers.get("retry-after")) || undefined;
  throw err;
}

import os, requests

class SalesfinityError(Exception):
    def __init__(self, res):
        try:
            body = res.json()
        except ValueError:
            # A failure at the network edge may not be JSON.
            body = {}
        self.status_code = body.get("statusCode", res.status_code)
        self.error = body.get("error", res.reason)
        self.request_id = body.get("request_id") or res.headers.get("X-Request-Id")
        message = body.get("message")
        self.detail = "; ".join(message) if isinstance(message, list) else message
        self.retryable = self.status_code == 429 or self.status_code >= 500
        # On a 429, the number of seconds to wait before retrying.
        self.retry_after = int(res.headers.get("Retry-After", 0)) or None
        super().__init__(
            f"Salesfinity {self.status_code} {self.error}: {self.detail} (request {self.request_id})"
        )


def salesfinity(path, **kwargs):
    res = requests.get(
        f"https://client-api.salesfinity.co{path}",
        headers={"x-api-key": os.environ["SALESFINITY_API_KEY"]},
        timeout=60,
        **kwargs,
    )
    if not res.ok:
        raise SalesfinityError(res)
    return res.json()

Reporting a problem

Email [email protected] or use the help center. Include:

The request_id from the error body, or the X-Request-Id response header. It lets Salesfinity find the exact request.
The request method and path, for example GET /v1/call-log.
The timestamp of the request, with its timezone.
The error and statusCode from the response body.

Never include your API key in a support message.

Next steps

Stay under the rate limits

Per-team budgets, the headers that report them, and pacing.

Test safely on live data

Read-only first, a test team, and writes that reach the dialer.

Get started

MCP server

MCP reference

MCP use cases

Dialer API

Calls and analytics API

Enrichment API

Sequencer API

The error envelope

Request IDs

The order checks run in

Status codes

400 Bad Request

402 Payment Required

403 Forbidden

404 Not Found

409 Conflict

413 Payload Too Large

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

502 Bad Gateway and 504 Gateway Timeout

Other statuses

Which errors are retryable

Retrying writes safely

Handling errors in code

Reporting a problem

Next steps

Stay under the rate limits

Test safely on live data

​The error envelope

​Request IDs

​The order checks run in

​Status codes

​400 Bad Request

​402 Payment Required

​403 Forbidden

​404 Not Found

​409 Conflict

​413 Payload Too Large

​422 Unprocessable Entity

​429 Too Many Requests

​500 Internal Server Error

​502 Bad Gateway and 504 Gateway Timeout

​Other statuses

​Which errors are retryable

​Retrying writes safely

​Handling errors in code

​Reporting a problem

​Next steps

Stay under the rate limits

Test safely on live data

The error envelope

Request IDs

The order checks run in

Status codes

400 Bad Request

402 Payment Required

403 Forbidden

404 Not Found

409 Conflict

413 Payload Too Large

422 Unprocessable Entity

429 Too Many Requests

500 Internal Server Error

502 Bad Gateway and 504 Gateway Timeout

Other statuses

Which errors are retryable

Retrying writes safely

Handling errors in code

Reporting a problem

Next steps