Error Handling

When a request to the integration API fails, the response includes a JSON body with information about the error.

Error format

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key missing or invalid"
}

Field	Type	Description
`statusCode`	number	HTTP status code
`error`	string	Error name
`message`	string	Detailed description of the problem

Error codes

Status	Code	Description	Solution
`401`	Unauthorized	API key missing or invalid	Verify that the `x-api-key` header is present and that the key has not been revoked
`403`	Forbidden	The key does not have the required permission	Confirm that the key has the necessary permissions: `VIEW_ACTIVITIES` for queries, `SUBMIT_ACTIVITY_RESULT` for submitting results
`400`	Bad Request	Validation error in the request body	Check that the body complies with the documented format. Verify data types, required fields, and valid result codes
`404`	Not Found	Resource not found	Confirm that the `activity_id`, `commerce_external_id`, or other identifier exists in the tenant
`409`	Conflict	The activity already has a registered result	Use `hard_override: true` in the request body if you need to overwrite the existing result

Common errors and diagnostics

401 — Unrecognized key

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "API key missing or invalid"
}

Possible causes:

The x-api-key header is not present in the request
The key was revoked from the administration panel
The key has an expired expiration date
Formatting error (spaces, extra characters)

403 — Insufficient permission

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

Possible causes:

The key does not include the required permission for the endpoint
Contact the tenant administrator to verify the permissions assigned to the key

400 — Validation error

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "task_result.result must be a valid result type code"
}

Possible causes:

Missing required fields (commerce_external_id, occurred_at, status, task_result.result)
Invalid result code — see List Configurations to get valid codes
Missing future_scheduled_at when the result type requires it
Invalid date format (must be ISO 8601)

409 — Duplicate result

{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Activity already has a result"
}

The activity already has a registered result. If you need to overwrite the existing result, send the request again with "hard_override": true in the body.

Recommendations

Log errors: Store the error response body for later diagnostics
Implement retries for 5xx errors (server errors) with exponential backoff
Do not retry 4xx errors without correcting the request — these indicate a problem with the submitted data
Validate before sending: Query the available result types before submitting results to avoid 400 errors