Skip to main content

​
Error Handling

The Trigify API uses a consistent error response format across all endpoints. Every error includes a machine-readable code, a human-readable message, and an optional suggestion for how to resolve the issue.

​
Error Response Format

All error responses follow this structure: 
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Workflow has 2 validation error(s)",
    "details": {
      "errors": [
        "Step 'Enrich profile' uses unknown action kind 'enrich/profle'",
        "Step 'Send to CRM' is missing required input 'email'"
      ]
    },
    "suggestion": "Use /v1/workflows/actions to see available actions and their required inputs"
  }
}

​
Response Fields

FieldTypeDescription
successbooleanAlways false for error responses
error.codestringMachine-readable error code (see table below)
error.messagestringHuman-readable description of what went wrong
error.detailsobject | nullAdditional context such as validation errors or conflicting fields
error.suggestionstring | nullActionable advice for resolving the error
The suggestion field is provided for common, recoverable errors. Use it to guide your error handling logic or surface helpful messages to end users.

​
Error Codes

CodeHTTP StatusDescription
VALIDATION_ERROR400Request body or query parameters failed validation
BAD_REQUEST400Malformed request that does not match the expected format
AUTH_REQUIRED401No authentication credentials were provided
INVALID_API_KEY401The API key is invalid or has been revoked
TOKEN_EXPIRED401The authentication token has expired
FORBIDDEN403The API key does not have permission for this operation
SUBSCRIPTION_INACTIVE403Your subscription is not active (expired, cancelled, or past due)
INSUFFICIENT_CREDITS403Not enough credits to complete the requested operation
NOT_FOUND404The requested resource does not exist
CONFLICT409The request conflicts with existing state (e.g., duplicate name)
RATE_LIMITED429Too many requests; see Rate Limits for details
INTERNAL_ERROR500An unexpected server error occurred
SERVICE_UNAVAILABLE503The service is temporarily unavailable

​
Error Examples

​
Authentication Error

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is not valid",
    "details": null,
    "suggestion": "Check your API key in the Trigify dashboard at https://app.trigify.io/settings/api-keys"
  }
}

​
Validation Error

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request parameters",
    "details": {
      "errors": [
        "\"days\" must be between 1 and 365",
        "\"limit\" must be between 1 and 500"
      ]
    },
    "suggestion": null
  }
}

​
Insufficient Credits

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits to complete this operation",
    "details": {
      "required": 5,
      "available": 2
    },
    "suggestion": "Upgrade your plan or wait for your credit balance to reset"
  }
}

​
Resource Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Workflow not found",
    "details": null,
    "suggestion": "Check the workflow ID and ensure it belongs to your organisation"
  }
}

​
Rate Limited

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Maximum 100 requests per minute allowed.",
    "details": null,
    "suggestion": "Wait for the rate limit window to reset. Check RateLimit-Reset header for timing."
  }
}

​
Handling Errors in Code

# Check HTTP status code
response=$(curl -s -w "\n%{http_code}" -X GET "https://api.trigify.io/v1/org" \
  -H "x-api-key: YOUR_API_KEY")

http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)

if [ "$http_code" -ne 200 ]; then
  echo "Error ($http_code): $body"
fi

​
Best Practices

  1. Always check success: Every response includes a success boolean. Check it before accessing data.
  2. Use error codes, not messages: The code field is stable and machine-readable. The message field may change.
  3. Respect rate limits: Monitor RateLimit-Remaining headers to avoid hitting the limit.
  4. Handle retries gracefully: For RATE_LIMITED and SERVICE_UNAVAILABLE, implement exponential backoff.
  5. Log the full error: Store code, message, details, and suggestion for debugging.