Errors

The Crane Ledger REST API uses a consistent JSON structure for all error responses. This page describes that format, common error types, and how to handle them in your application.

Error Response Format

All API errors return a JSON object with an error key:

{
  "error": {
    "type": "validation_error",
    "code": "transaction_does_not_balance",
    "message": "Transaction does not balance",
    "details": {
      "total_debits": 150.00,
      "total_credits": 100.00,
      "difference": 50.00
    },
    "status": 400
  }
}

Error Object Fields

FieldTypeDescription
typestringHigh-level error category
codestringMachine-readable error code
messagestringHuman-readable description
detailsobjectOptional; additional context (e.g. validation fields)
statusintegerHTTP status code

The details object, when present, often includes field-level validation errors or extra context to fix the request.

Common Error Types

TypeHTTP StatusDescription
authentication_error401Invalid, missing, or expired API key
authorization_error403API key valid but lacks permission for this operation
validation_error400Invalid request body or parameters
not_found_error404Resource does not exist or is not accessible
business_rule_error422Request is valid but violates a business rule
rate_limit_error429Too many requests; retry after backoff
credit_limit_error402Insufficient credits for this operation
server_error500Internal error; retry with backoff

Example Error Responses

Authentication Error (401)

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or expired",
    "status": 401
  }
}

Validation Error (400)

{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "Request validation failed",
    "details": {
      "fields": {
        "entries": "At least two entries are required",
        "entries[0].amount": "Must be a positive number"
      }
    },
    "status": 400
  }
}

Business Rule Error (422)

{
  "error": {
    "type": "business_rule_error",
    "code": "transaction_does_not_balance",
    "message": "Transaction does not balance",
    "details": {
      "total_debits": 150.00,
      "total_credits": 100.00,
      "difference": 50.00
    },
    "status": 422
  }
}

Rate Limit Error (429)

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded. Try again later.",
    "retry_after": 60,
    "status": 429
  }
}

Use the retry_after value (seconds) to wait before retrying. See Rate Limits for headers and retry guidance.

Handling Errors in Code

Check the HTTP status and parse the error object to decide how to respond:

Troubleshooting

  1. 401 Unauthorized – Verify the API key is correct, not expired, and sent as Authorization: Bearer <key>.
  2. 403 Forbidden – The key may not have permission for this resource or action; check key permissions in the Dashboard or API Keys.
  3. 404 Not Found – Confirm the URL path and organization ID. Ensure the resource ID exists and belongs to the organization.
  4. 422 Business rule errors – Read the message and details to see which rule was violated (e.g. unbalanced transaction, invalid state transition).
  5. 429 Rate limit – Implement exponential backoff and respect Retry-After or the response retry_after value. See Rate Limits.
  6. 5xx Server errors – Retry with backoff; if the issue persists, contact support.

Idempotency

For critical write operations, use idempotency keys where supported so that retries do not create duplicate resources.

Need help?

Create a free account to access our support portal. Once signed in, use the Support tab in your dashboard to submit a support ticket — our team typically responds within 24 hours.