Reten Docs

Error Handling

Error format, status codes, and solutions for the integration API.

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"
}
FieldTypeDescription
statusCodenumberHTTP status code
errorstringError name
messagestringDetailed description of the problem

Error codes

StatusCodeDescriptionSolution
401UnauthorizedAPI key missing or invalidVerify that the x-api-key header is present and that the key has not been revoked
403ForbiddenThe key does not have the required permissionConfirm that the key has the necessary permissions: VIEW_ACTIVITIES for queries, SUBMIT_ACTIVITY_RESULT for submitting results
400Bad RequestValidation error in the request bodyCheck that the body complies with the documented format. Verify data types, required fields, and valid result codes
404Not FoundResource not foundConfirm that the activity_id, commerce_external_id, or other identifier exists in the tenant
422Unprocessable EntityThe request is valid but the activity's state does not allow the operationVerify that the activity is in an actionable state (READY or DISPATCHED) and that its execution date has not crossed the end-of-day cutoff

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, 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)

422 — Non-processable state

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "The activity is not in an actionable state."
}

Possible causes:

  • The linked activity is not in an actionable state (READY or DISPATCHED)
  • The activity's execution date has already crossed the end-of-day cutoff — past that cutoff, an auto-close runs and may register the result (as NOT_EXECUTED). Standalone executions (STANDALONE, without activity_id) are exempt from this rule