Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cula.tech/llms.txt

Use this file to discover all available pages before exploring further.

Every non-2xx response returns a consistent error object.

​
Error response structure

{
  "error": {
    "type": "validation_error",
    "code": "invalid_param",
    "message": "data_points[0].input_value must be a number",
    "param": "data_points[0].input_value",
    "request_id": "req_01abc...",
    "doc_url": "https://docs.cula.tech/technical-reference/error-handling",
    "details": [
      {
        "code": "invalid_type",
        "param": "data_points[0].input_value",
        "message": "Expected number, received string"
      }
    ]
  }
}
FieldTypeDescription
typestringError category (see below)
codestringMachine-readable error code
messagestringHuman-readable summary
paramstring?The field that caused the error (if applicable)
doc_urlstring?Link to relevant documentation
request_idstringUnique request identifier for support tickets
detailsarray?Per-field errors for multi-field validation failures

​
Error types

TypeDescription
validation_errorRequest body or parameters failed validation
conflictResource state conflict (duplicate external_id, finalised submission)
not_foundResource does not exist or is outside key scope
auth_errorMissing, invalid, or expired API key
rate_limitToo many requests
internal_errorServer-side failure

​
HTTP status codes

StatusMeaning
200Success (GET, PUT)
201Created (POST)
204No content (DELETE)
400Bad request (malformed JSON, missing required fields)
401Unauthorized (missing or invalid API key)
403Forbidden (resource outside key scope)
404Not found
409Conflict
422Unprocessable entity (valid JSON, but semantically invalid)
429Rate limited
5xxServer error

​
Conflict handling

​
Duplicate external ID (409)

If you POST a resource with an external_id that already exists, the server returns 409 with the existing resource reference: 
{
  "error": {
    "type": "conflict",
    "code": "external_id_in_use",
    "message": "A material-sourcing resource with this external_id already exists",
    "request_id": "req_01xyz...",
    "existing": {
      "id": "stp_01kqzcjrpxf27tge33jwvjhkff",
      "external_id": "MY-STEP-001"
    }
  }
}
Use the returned id with PUT to update the resource.

​
Finalised submission (409)

A PUT or PATCH on a resource whose downstream submission has been finalised returns: 
{
  "error": {
    "type": "conflict",
    "code": "resource_in_finalised_submission",
    "message": "This resource belongs to a finalised submission and cannot be modified",
    "request_id": "req_01xyz..."
  }
}
Resources in finalised submissions are immutable. Contact support if you need to correct data after finalisation.

​
Idempotency

POST with the same external_id is not idempotent. It returns 409 if the resource already exists, even when the payload matches. To update an existing resource, use PUT.

​
Multi-field validation

When multiple fields fail validation, the top-level message provides a summary and details[] contains individual field errors: 
{
  "error": {
    "type": "validation_error",
    "code": "invalid_params",
    "message": "2 validation errors",
    "request_id": "req_01abc...",
    "details": [
      { "code": "required", "param": "config_id", "message": "config_id is required" },
      { "code": "invalid_type", "param": "data_points[0].input_value", "message": "Expected number" }
    ]
  }
}
Always include request_id when contacting support about an error.