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": "Invalid or revoked API key"
}

Error codes

Common errors and diagnostics

401 — Unrecognized key

{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid or revoked API key"
}

Possible causes:

• The key was revoked from the administration panel
• The key has an expired expiration date
• Formatting error (spaces, extra characters)
• The key's owner is inactive — in that case the message is API key owner is inactive or not found
• The API could not validate the key at that moment — in that case the message is API key validation failed; retry the request

A request that carries no key does not receive this 401. The API only reads x-api-key as a key when its value starts with rtn_sk_; any other value counts as no key. Without a key and without x-tenant-id, the API responds 400 Bad Request with Missing required header: x-tenant-id; with x-tenant-id but no credentials, it responds 401.

Project errors

On GET /api/integration/activities/tasks and POST /api/integration/activity-results/tasks, x-project-id is optional: both are project-optional endpoints. When the header is sent, the API checks it before the permissions and the body. The 400 of a result without activity_id is not part of that check: it comes after the body is validated, so an error in the body is reported first. How each key chooses its project is explained in Key scope.

403 — Insufficient permission

{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Required permissions: activity:view"
}

Possible causes:

• The key does not include the required permission for the endpoint
• Ask the key's owner to edit its permissions with PUT /api/api-keys/:id/permissions or from Settings → API Keys

400 — Validation error

The API responds 400 when the body does not match the documented format.

Possible causes:

• Missing required fields: occurred_at and task_result.result always; commerce_external_id only when activity_id is absent (standalone executions)
• Invalid date format (must be ISO 8601)
• activity_id is not a valid UUID
• Fields that are not part of the documented body

422 — Non-processable state

{
  "statusCode": 422,
  "error": "Unprocessable Entity",
  "message": "La actividad no está en un estado válido para registrar resultado."
}

Possible causes:

• The linked activity is not in a state that accepts a result. READY, DISPATCHED and RETRYING accept one; COMPLETED also does, and submitting again updates the activity's existing result; CANCELED and FAILED do not — message above
• The activity's execution date has already crossed the end-of-day cutoff — La actividad corresponde a un día ya cerrado y no admite registrar resultado. 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 and the previous one
• The result code in task_result.result does not exist or is not active — El tipo de resultado seleccionado no está activo. See List Configurations to get valid codes
• The result type requires task_result.future_scheduled_at and it was not sent — Este tipo de resultado requiere una fecha comprometida.
• task_result.future_scheduled_at falls on a day before today, in the tenant's time zone — La fecha programada no puede ser en el pasado.