Error Codes

The API uses standard HTTP status codes and returns detailed error information in a consistent format.

Error Response Format

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": { }
  }
}

HTTP Status Codes

Authentication Errors (401)

Missing Credentials

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing API credentials"
  }
}

Cause: The api-key or api-secret header is missing.

Solution: Include both headers in your request.

Invalid Credentials

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API credentials"
  }
}

Cause: The API key or secret is incorrect.

Solution: Verify your credentials are correct.

Expired Key

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key expired"
  }
}

Cause: The API key has passed its expiration date.

Solution: Create a new API key.

Permission Errors (403)

Insufficient Permissions

{
  "error": {
    "code": "FORBIDDEN",
    "message": "API key lacks transactions:create permission"
  }
}

Cause: Your API key doesn't have the required permission for this action.

Solution: Create a new API key with the appropriate permissions, or modify the existing key's permissions.

Validation Errors (400)

Missing Required Field

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "date is required"
  }
}

Invalid Field Value

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "category must be one of: bank, credit_card"
  }
}

Invalid JSON

{
  "error": {
    "code": "INVALID_JSON",
    "message": "Invalid JSON body"
  }
}

Not Found Errors (404)

Resource Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Transaction not found"
  }
}

Cause: The requested resource doesn't exist or doesn't belong to your organization.

Error Handling Best Practices

1. Always check the status code before parsing the response body
2. Log error details for debugging purposes
3. Implement retry logic for 5xx errors with exponential backoff
4. Don't retry 4xx errors without fixing the underlying issue

Example Error Handling (JavaScript)

async function apiRequest(url, options) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'api-key': API_KEY,
      'api-secret': API_SECRET,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error?.message || 'API request failed');
  }

  if (response.status === 204) {
    return null;
  }

  return response.json();
}