Error Handling

The API uses standard HTTP status codes and returns errors in a consistent JSON format.

Error response format

{
  "error": {
    "code": "not_found",
    "message": "Partner not found"
  }
}

Error codes

HTTP Status	Code	Description
`401`	`unauthorized`	Missing or invalid API key
`403`	`forbidden`	API key lacks required permission (read or write), or the partnership has locked the field being changed (see Partnership locks)
`403`	`module_disabled`	The requested module is not enabled for your account
`404`	`not_found`	The requested resource does not exist
`409`	`conflict`	The action conflicts with existing data (e.g., deleting a stage in use)
`400`	`validation_error`	Request body or query parameters failed validation
`400`	`distributor_commissions_unsupported`	Distributor commission rules are not supported — use `referral` or `reseller`
`429`	`rate_limit_exceeded`	Too many requests — wait and retry
`500`	`internal_error`	Unexpected server error

Handling errors

Check the HTTP status code first, then use error.code for programmatic handling:

const response = await fetch("https://api.journeybee.io/v1/partners", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Acme Corp" }),
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case "unauthorized":
      // Re-authenticate or check API key
      break;
    case "validation_error":
      // Fix request body based on error.message
      break;
    case "rate_limit_exceeded":
      // Wait for Retry-After header duration
      break;
    default:
      // Log and retry or alert
      break;
  }
}

Validation errors

When request validation fails, the message field describes which fields are invalid:

{
  "error": {
    "code": "validation_error",
    "message": "body/name: Required"
  }
}

Conflict errors

Delete operations on configuration resources (stages, tiers, categories, tags, custom fields) return 409 Conflict if the resource is currently in use:

{
  "error": {
    "code": "conflict",
    "message": "Stage \"Active\" is in use by 12 record(s) and cannot be deleted"
  }
}

Reassign the records to a different stage/tier/category before retrying the delete.

Custom field validation

Creating or updating a lead, deal, or partner with custom field values — whether inline on the entity itself, or via POST/PATCH/DELETE /v1/custom-field-values and the per-entity custom-field endpoints (PUT/ PATCH/DELETE /v1/leads/:uuid/custom-fields, .../deals/:uuid/custom-fields, .../partners/:uuid/custom-fields) — is validated server-side against each field’s required flag, its partner_type scope, and any active custom field rules (visibility, locking, auto-population). A violation returns a 400 validation_error with a details array — one entry per rejected field:

Field	Description
`field`	The custom field’s UUID
`label`	The custom field’s label (omitted when it can’t be disclosed)
`reason`	A machine-readable reason code (see below)
`message`	A human-readable explanation

reason is one of:

Reason	Meaning
`missing_required`	A required field (visible under current rule state) was not supplied on create
`required_cannot_blank`	An update attempted to clear a required field that currently has a value
`hidden_by_rule`	A value was submitted for a field a rule currently hides
`locked_by_rule`	A value was submitted for a field a rule locks to a different value
`not_accessible`	The field exists but isn’t available on this surface
`unknown_field`	No custom field matches the given UUID
`invalid_value`	The submitted value doesn’t match the field’s type
`invalid_option`	A `select`/`multi_select` value references an option that doesn’t exist

Deleting a custom field value

DELETE is treated as submitting an empty value for the field, so the same checks apply:

Deleting a visible, required value returns required_cannot_blank — clearing it would leave the entity without a value a required field demands.
Deleting a value that’s currently locked by an active custom field rule returns locked_by_rule — the value can’t be changed (including to empty) while the rule that sets it is active.
Deleting a hidden field’s value, or a value with no active constraints, succeeds normally (204).

Example response (400):

{
  "error": {
    "code": "validation_error",
    "message": "\"Country\" is required; \"Renewal Terms\" is only visible when \"Deal Type\" is \"Enterprise\"",
    "details": [
      {
        "field": "b3f1c2a0-1111-4a2b-9c3d-000000000001",
        "label": "Country",
        "reason": "missing_required",
        "message": "\"Country\" is required"
      },
      {
        "field": "b3f1c2a0-2222-4a2b-9c3d-000000000002",
        "label": "Renewal Terms",
        "reason": "hidden_by_rule",
        "message": "\"Renewal Terms\" is only visible when \"Deal Type\" is \"Enterprise\""
      }
    ]
  }
}

Partnership locks

On the partner API, a vendor can disable editing of lead status or deal stage for a partnership. While a lock is on, a request that would change the locked value returns 403 forbidden and nothing in the request is saved. The lock that applies is the calling partner’s own partnership. The details array holds one entry with reason locked_by_partnership, and field is one of:

Field	Rejected when
`status`	`updatePartnerLead` changes the lead’s status while lead status is locked
`rejected_reason`	`updatePartnerLead` changes the rejected reason while lead status is locked
`accepted_reason`	`updatePartnerLead` changes the accepted reason while lead status is locked
`fields.stage_id`	`updatePartnerDeal` changes the deal’s stage while deal stage is locked
`stage_uuid`	`createPartnerDeal` sends a stage other than the default while deal stage is locked

Re-sending the current value, or omitting stage_uuid on create (the deal then starts in the default stage), still succeeds. For rejected_reason and accepted_reason, the current value is the one the lead response shows you: it is null when the vendor hides the reason from partners or the lead is not in that reason’s status, so echoing null back is not a change. Example response (403):

{
  "error": {
    "code": "forbidden",
    "message": "Deal stage changes are locked for this partnership",
    "details": [
      {
        "field": "fields.stage_id",
        "reason": "locked_by_partnership",
        "message": "Deal stage changes are locked for this partnership"
      }
    ]
  }
}

Getting Started

SDKs & Tools

Embedding

Resources

Error Handling

Error Handling

Error response format

Error codes

Handling errors

Validation errors

Conflict errors

Custom field validation

Deleting a custom field value

Partnership locks

​Error Handling

​Error response format

​Error codes

​Handling errors

​Validation errors

​Conflict errors

​Custom field validation

​Deleting a custom field value

​Partnership locks

Error Handling

Error response format

Error codes

Handling errors

Validation errors

Conflict errors

Custom field validation

Deleting a custom field value

Partnership locks