Errors

Every error on the integration API is JSON with the same shape, an HTTP status that means what it usually means, and a stable machine-readable code. Each error’s documentation_url links to that code’s section on this page.

The error object

{
  "error": {
    "code": "validation_failed",
    "message": "The request contains invalid data.",
    "details": [
      { "field": "mobile_number", "message": "The mobile number field is required when email is not present." }
    ],
    "request_id": "01K4R4Z2N7Q9X0F3M6C8V1B5D2",
    "documentation_url": "https://developers.bytephase.com/errors#validation_failed"
  },
  "message": "The request contains invalid data."
}

Field	Always present	Meaning
error.code	Yes	Stable, snake_case. Branch on this, never on the message. New codes may be added; existing ones will not change meaning.
error.message	Yes	Human-readable and safe to show to a user. Wording may change and may be translated.
error.details	Only on validation_failed	One entry per problem: field (dot notation for nested fields, e.g. address.city) and message.
error.request_id	Yes	Matches the X-Request-Id response header. Quote it to support.
error.documentation_url	Yes	A link to the relevant section of this page.
message (top level)	Yes	A copy of error.message, kept for older clients that read only the top-level message. Prefer error.message.

The X-Request-Id header is on every response from /api/integrations/* and /api/zapier/*, success or failure.

Summary

HTTP	code	Retry?
400	malformed_request	No
401	credential_missing	No
401	credential_invalid	No
401	invalid_signature	No
403	integration_not_permitted	No
403	business_not_active	No
404	unsupported_adapter	No
404	business_not_found	No
404	not_found	No
409	idempotency_conflict	No
422	validation_failed	No
422	unreadable_submission	No
423	workspace_not_ready	Yes, after a short wait
429	rate_limit_exceeded	Yes, after Retry-After
500	internal_error	Yes, with the same Idempotency-Key

Retry only 429, 423, 500 and network failures, always with the same Idempotency-Key. Every other 4xx will fail again identically until you change the request.

Error codes

malformed_request

400 Bad Request. The body could not be read — usually invalid JSON, or a Content-Type that does not match the body. Fix the request; do not retry it unchanged.

credential_missing

401 Unauthorized. No API key arrived. Add the Authorization: Bearer bp_… header (or X-API-Key). If you are sure you sent it, check that a proxy or a tool setting is not stripping the Authorization header — switching to X-API-Key is a quick way to tell. See Authentication.

credential_invalid

401 Unauthorized. The key is unknown, disabled, rotated, expired — or it belongs to a different workspace than the URL points at. Check the base URL first (keys only exist inside the workspace that issued them), then copy the key again from BytePhase. Do not retry unchanged.

invalid_signature

401 Unauthorized. A Typeform or Tally.so webhook carried a signature that did not verify against the signing secret on the integration, or carried none. Make sure the secret pasted into the provider matches the one generated in BytePhase, and that the provider is signing the webhook at all. See Inbound Forms.

integration_not_permitted

403 Forbidden. The key authenticated, but is not allowed here. One of:

• the key’s provider type is not allowed on this endpoint — for example a Website key calling a Zapier read endpoint;
• the key belongs to another provider’s receiver — an IndiaMART key on the Justdial URL, or the reverse.

Use a key of the right type. Do not retry unchanged. (A business_id problem is reported separately as business_not_found or business_not_active.) See Authentication.

business_not_active

403 Forbidden. The business_id you sent names a business in this workspace that is not active. Records can only be created against an active business. Send the id of an active business, or omit business_id to use the workspace’s default business. Do not retry unchanged.

unsupported_adapter

404 Not Found. /api/integrations/ingest/{adapter} was called with an adapter name that does not exist. Use one of canonical, form, typeform, jotform, tally-so, indiamart, justdial. See Inbound Forms.

business_not_found

404 Not Found. The business_id you sent does not match any business in this workspace. Check the value, or omit business_id to use the workspace’s default business. Do not retry unchanged.

not_found

404 Not Found. The path or resource does not exist. Check the path against the reference.

idempotency_conflict

409 Conflict. Reserved for a reused Idempotency-Key sent with a different body. Not currently raised — today a reused key returns the original response regardless of body — so never reuse a key across submissions. See Idempotency.

validation_failed

422 Unprocessable Content. A required field is missing, a value is the wrong type or too long, or the destination could not be determined. details lists every problem at once, so fix them all in one go:

{
  "error": {
    "code": "validation_failed",
    "message": "The request contains invalid data.",
    "details": [
      { "field": "name", "message": "The name field is required." },
      { "field": "email", "message": "The email field must be a valid email address." }
    ],
    "request_id": "01K4R4Z2N7Q9X0F3M6C8V1B5D2",
    "documentation_url": "https://developers.bytephase.com/errors#validation_failed"
  },
  "message": "The request contains invalid data."
}

The most common cause is a lead or self check-in with neither mobile_number nor email; one of the two is required. Field rules are in Custom Integrations. Do not retry unchanged.

unreadable_submission

422 Unprocessable Content. A provider receiver could not make sense of the payload it was sent. Check that the provider is posting the format the receiver expects — for example JotForm’s webhook must be sent as a form post, and Typeform’s as JSON. See Inbound Forms.

workspace_not_ready

423 Locked. The workspace is still being set up. Retry after a short wait.

rate_limit_exceeded

429 Too Many Requests. More than 60 requests in a minute on this key. Wait for the number of seconds in the Retry-After header, then retry with the same Idempotency-Key. See Rate Limits.

internal_error

500 Internal Server Error. Our fault. Retry with the same Idempotency-Key after a short wait. If it persists, contact support with the request_id.

Errors that are not in the table

• 412 with a plain message means the workspace could not be identified from the host you sent the request to. It happens before the request reaches the API proper, so it does not carry the error object. It is nearly always a base URL mistake — see Environments.
• 405 Method Not Allowed means the path exists but not for that method — for example GET on /api/integrations/leads. Only the Justdial receiver accepts GET.

Reading errors in Zapier and n8n

Both tools surface the HTTP status and the response body. In n8n, set the HTTP Request node to continue on error and branch on error.code. In Zapier, a non-2xx response marks the step as errored and shows message.