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)
`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
`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\""
      }
    ]
  }
}

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

​Error Handling

​Error response format

​Error codes

​Handling errors

​Validation errors

​Conflict errors

​Custom field validation

​Deleting a custom field value

Error Handling

Error response format

Error codes

Handling errors

Validation errors

Conflict errors

Custom field validation

Deleting a custom field value