Docs/Errors

Errors

Errors use ordinary HTTP status codes and always return the same JSON: a code to branch on and an error sentence you can show.

Error response

{
  "error": "This person is already in your workspace.",
  "code": "duplicate",
  "duplicates": [
    {
      "type": "contact",
      "id": "66f2a1c0e4b0a1b2c3d4e5f6",
      "name": "Priya Nair",
      "reason": "Same email",
      "yours": true
    }
  ],
  "can_force": false
}

409 Conflict

codeThe exact reason, from the list below. It does not change, so branch on this.

errorPlain words for logs or your own screens. It may be reworded, so do not match on it.

…Some codes add details: required and granted, unknown_fields and accepted_fields, missing_fields, problems, duplicates and can_force, deal_id.

All error codes

Status	Code	What happened	What to do
401	`authentication_required`	No key was sent.	Send `Authorization: Bearer` with your key, or `X-API-Key`.
401	`invalid_key`	The key is wrong, revoked or expired. One answer for all three.	Check you copied the whole key. If it was revoked, make a new one in Settings › API and webhooks.
403	`organisation_inactive`	The workspace is not active.	The workspace is closed or suspended. Ask its admin.
403	`seat_inactive`	The person or service account this key acts for is no longer active.	The key acts for a person or service account that was suspended. Use another key.
403	`missing_scope`	The key was not given the scope this endpoint needs. `required` and `granted` say which.	Add the scope named in `required`, or use a key that has it.
403	`forbidden`	The key’s role or reach does not allow this.	The key’s role does not allow this, or a condition on the role (hours, network) refused it.
404	`not_found`	No such record, or one the key cannot reach. The same answer for both.	Check the id, and that the key’s workspace and reach include the record.
400	`invalid_request`	The request is missing something or a value is wrong. `problems` lists each one when there are several.	Read `error` (and `problems` or `missing_fields`), fix the value and send again.
400	`unknown_fields`	The body has a field this endpoint does not accept. `unknown_fields` and `accepted_fields` say which.	Remove the fields in `unknown_fields`. `accepted_fields` lists what the endpoint takes.
400	`reason_required`	Moving a deal to a lost stage needs `reason_code`.	Send `reason_code`, one of your lost reasons.
422	`stage_requirements_missing`	The stage needs fields the deal does not have yet. `missing_fields` lists each `{ key, label }`; send them in `fields`.	Send the fields in `missing_fields` in the move’s `fields`, then move again.
409	`suppressed`	The contact was deleted and is on the do-not-contact list, so the same address is not added again.	They were deleted and asked not to be contacted. Keep them out of your source of contacts.
409	`duplicate`	The record already exists. `duplicates` (contacts, companies) or `deal_id` (deals) points at it when the key can reach it.	Use the record in `duplicates` or `deal_id`. For a contact or company with only a similar name, send `force: true`.
409	`conflict`	The record changed in a way that stops this request.	Read the record again and decide from what it says now.
409	`idempotency_key_in_use`	A request with this Idempotency-Key is still running. Retry shortly.	Wait a moment and retry with the same key.
422	`idempotency_key_reused`	This Idempotency-Key was used for a different request.	Use a new Idempotency-Key for a new request.
400	`unsupported_version`	The `Workloom-Version` header names no version. `versions` lists the ones there are.	Send one of the versions in `versions`, or leave `Workloom-Version` out to use your key’s.
404	`sandbox_only`	This endpoint works in a developer sandbox only: sandbox-api.useworkloom.com, with a `wl_sbx_` key.	Send it to the sandbox, `https://sandbox-api.useworkloom.com/api/public/v1`, with a `wl_sbx_` key.
401	`sandbox_key`	A developer sandbox key (`wl_sbx_`) was sent to the live API. Send it to sandbox-api.useworkloom.com.	Send a `wl_sbx_` key to the sandbox address, or use a live key here.
429	`rate_limited`	More requests a minute than the key is allowed. Wait `Retry-After` seconds.	Wait `Retry-After` seconds, then retry.
500	`internal_error`	Something failed on our side. Safe to retry with the same Idempotency-Key.	Retry with backoff and the same Idempotency-Key. If it keeps happening, email us.

Safe retries

Retry 429 and 5xx answers with backoff. Send an Idempotency-Key header on every POST: if a retry reaches Workloom twice, the second gets the first answer instead of making a duplicate. A key is kept 24 hours. Using it again for a different request gets 422 idempotency_key_reused, and using it while the first request is still running gets 409 idempotency_key_in_use.

Was this page useful?