Error Codes

When a request fails, the Chainabit API returns a structured error response within the standard response envelope. This page documents all error codes and their meanings.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error",
    "details": {}
  },
  "meta": {
    "requestId": "req_abc123",
    "durationMs": 5
  }
}

The details field is optional and contains additional context when available (e.g., field-level validation errors).

Error Codes

Code	HTTP Status	Description
VALIDATION_ERROR	400	The request body, query parameters, or path parameters failed validation.
UNAUTHORIZED	401	The request is missing a valid authentication token, or the token has expired.
FORBIDDEN	403	The authenticated user does not have permission to perform this action.
NOT_FOUND	404	The requested resource does not exist, or the user does not have access to it.
RATE_LIMIT_EXCEEDED	429	The user has exceeded the rate limit for this endpoint.
INTERNAL_ERROR	500	An unexpected error occurred on the server.

Examples

VALIDATION_ERROR (400)

Returned when the request payload does not match the expected schema.

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "name",
        "message": "name must not be empty"
      },
      {
        "field": "cadence",
        "message": "cadence must be one of: daily, weekly, custom"
      }
    ]
  },
  "meta": {
    "requestId": "req_1a2b3c",
    "durationMs": 3
  }
}

UNAUTHORIZED (401)

Returned when no token is provided, or the token is expired or malformed.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "meta": {
    "requestId": "req_4d5e6f",
    "durationMs": 1
  }
}

FORBIDDEN (403)

Returned when the user is authenticated but lacks the required role or entitlement.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "requestId": "req_7g8h9i",
    "durationMs": 2
  }
}

NOT_FOUND (404)

Returned when the requested resource does not exist or is not accessible to the user.

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Chain not found"
  },
  "meta": {
    "requestId": "req_0j1k2l",
    "durationMs": 8
  }
}

RATE_LIMIT_EXCEEDED (429)

Returned when the user exceeds the rate limit for the endpoint. See Rate Limiting for details.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded"
  },
  "meta": {
    "requestId": "req_3m4n5o",
    "durationMs": 1
  }
}

INTERNAL_ERROR (500)

Returned when an unexpected server error occurs. If you encounter this error consistently, contact support.

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  },
  "meta": {
    "requestId": "req_6p7q8r",
    "durationMs": 150
  }
}

When reporting an internal error, include the requestId from the meta field -- it helps the support team locate the relevant logs.