Errors

Slab5 returns structured errors with stable codes, request IDs, docs URLs, retry guidance, and remediation steps. The same error codes should be used by REST API responses and MCP tool calls when the failure has the same cause.

Envelope

All API errors use the same top-level envelope:

{
  "error": {
    "code": "missing_required_scope",
    "message": "The token does not include the scope required for this operation.",
    "request_id": "req_123",
    "docs_url": "https://docs.slab5.com/api/errors#missing_required_scope"
  }
}

Error responses may include additional fields when they help the caller fix the request, such as required_scope, field_errors, retry_after_seconds, or idempotency_key.

Request example

This request is missing the required name field:

curl https://api.slab5.com/v1/contacts \
  -H "Authorization: Bearer YOUR_SLAB5_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@acme.com","idempotency_key":"contact_missing_name"}'

Response examples

Validation errors return validation_failed:

{
  "error": {
    "code": "validation_failed",
    "message": "The request payload failed schema validation.",
    "field_errors": [
      {
        "field": "name",
        "message": "This field is required."
      }
    ],
    "request_id": "req_validation_123",
    "docs_url": "https://docs.slab5.com/api/errors#validation_failed"
  }
}

Idempotency conflicts return idempotency_conflict:

{
  "error": {
    "code": "idempotency_conflict",
    "message": "The idempotency key was reused with a different request body.",
    "idempotency_key": "contact_jane_doe_acme",
    "request_id": "req_idempotency_123",
    "docs_url": "https://docs.slab5.com/api/errors#idempotency_conflict"
  }
}

Retryable failures include enough context to retry safely:

{
  "error": {
    "code": "rate_limited",
    "message": "The workspace exceeded the current rate limit.",
    "retry_after_seconds": 30,
    "request_id": "req_rate_123",
    "docs_url": "https://docs.slab5.com/api/errors#rate_limited"
  }
}

Debugging

Use the request_id in the error response to find the matching audit event, API request event, MCP tool call event, and support log entry.

For user-facing troubleshooting, show the stable code and a short action. Avoid exposing internal exception names, diagnostic output, tenant IDs from other workspaces, or secrets.

Retry policy

Retry only errors marked retryable. For write requests, retry with the same JSON body and idempotency_key so duplicate records are not created.

Recommended retry behavior:

rate_limited: wait until the reset time when available, then retry.
internal_error: retry with exponential backoff and jitter.
Validation, authorization, scope, module, workspace, and resource errors should be fixed before retrying.

Error reference

unauthorizedHTTP 401

MVP

A valid bearer token is required.

Retryable: No. Fix the request before retrying.
Remediation: Create a workspace token and send it as Authorization: Bearer YOUR_SLAB5_TOKEN.

missing_required_scopeHTTP 403

MVP

The token does not include the scope required for this operation.

Retryable: No. Fix the request before retrying.
Remediation: Generate a token with the required scope, or choose an operation allowed by the current token.

workspace_not_foundHTTP 404

MVP

The workspace could not be found for this token.

Retryable: No. Fix the request before retrying.
Remediation: Confirm the token belongs to the intended workspace and has not been revoked.

resource_not_foundHTTP 404

MVP

The requested resource does not exist in this workspace.

Retryable: No. Fix the request before retrying.
Remediation: Check the resource ID and make sure it belongs to the same workspace as the token.

validation_failedHTTP 422

MVP

The request payload failed schema validation.

Retryable: No. Fix the request before retrying.
Remediation: Compare the payload to the documented schema and fix missing, unknown, or incorrectly typed fields.

idempotency_conflictHTTP 409

MVP

The idempotency key was reused with a different request body.

Retryable: No. Fix the request before retrying.
Remediation: Reuse an idempotency key only for the same logical write, or send a new key for a different request body.

rate_limitedHTTP 429

MVP

The workspace exceeded the current rate limit.

Retryable: Yes, with backoff.
Remediation: Back off until the rate-limit reset time and retry with the same idempotency key for writes.

module_not_enabledHTTP 403

MVP

The requested module is not enabled for this workspace.

Retryable: No. Fix the request before retrying.
Remediation: Enable the module for the workspace or remove module-specific operations from the workflow.

tool_not_foundHTTP 404

MVP

The requested MCP tool is not registered.

Retryable: No. Fix the request before retrying.
Remediation: List available MCP tools and call a registered tool name for the current API version.

mcp_auth_method_not_allowedHTTP 403

MVP

The MCP authentication method is not allowed by this workspace policy.

Retryable: No. Fix the request before retrying.
Remediation: Use an MCP auth method allowed by the workspace policy, or ask a workspace owner or admin to update the policy.

internal_errorHTTP 500

MVP

Slab5 could not complete the request.

Retryable: Yes, with backoff.
Remediation: Retry with exponential backoff. Include the request ID when contacting support if the error persists.