Skip to main content
This article will help you understand the most common API errors that may be encountered when utilizing Odin AI’s cloud platform. You will find details on the various HTTP status codes and specific error codes, providing you with essential troubleshooting steps to resolve these issues effectively. By understanding the error response format and the common pitfalls associated with API usage, you will be better equipped to handle errors and enhance your development experience.

​
Error Response Format

All API errors follow a consistent format: 
{
  "status_code": 400,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "detail": "Additional error details (optional)"
}
Some errors may also include:
  • error_id: Unique identifier for tracking the error
  • invalid_fields: List of fields that failed validation (for validation errors)

​
HTTP Status Codes

​
400 Bad Request

Client-side errors due to invalid input or malformed requests.
Error Code: VALIDATION_ERROR Status Code: 400Description: Request validation failed. One or more fields in the request are invalid.Common Causes:
  • Missing required fields
  • Invalid field format (e.g., invalid email, date format)
  • Field values outside allowed range
  • Invalid data types
Example Response:
{
  "status_code": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "invalid_fields": ["email", "project_id"]
  }
}
Troubleshooting:
  1. Review the invalid_fields array to identify problematic fields
  2. Check field requirements in the API documentation
  3. Verify data types match expected formats
  4. Ensure all required fields are provided
Error Code: INVALID_API_KEY
Status Code: 400Description: The provided API key is invalid or malformed.Troubleshooting:
  1. Verify the API key is correctly copied (no extra spaces)
  2. Check if the API key is active in My Account > API Keys
  3. Ensure you’re using the correct API key for your environment
  4. Regenerate the API key if necessary
Error Code: INVALID_CREDENTIALS
Status Code: 400Description: Authentication credentials are invalid.Troubleshooting:
  1. Verify email and password are correct
  2. Check if account is locked or disabled
  3. Try resetting your password
  4. Ensure you’re using the correct authentication method
Error Code: INVALID_OR_EXPIRED_JWT_TOKEN
Status Code: 400Description: The JWT token is invalid, expired, or malformed.Troubleshooting:
  1. Refresh your authentication token
  2. Log out and log back in
  3. Check token expiration time
  4. Verify token is being sent in the correct header format

​
401 Unauthorized

Authentication required or authentication failed.
Error Code: AUTHENTICATION
Status Code: 401Description: Authentication is required to access this resource.Troubleshooting:
  1. Ensure you’re logged in
  2. Check if your session has expired
  3. Verify authentication headers are included in the request
  4. Re-authenticate if necessary
Error Code: INVALID_BEARER_TOKEN
Status Code: 401Description: The Bearer token provided is invalid.Troubleshooting:
  1. Verify the token format: Bearer <token>
  2. Check if the token has expired
  3. Regenerate authentication token
  4. Ensure token is not revoked
Error Code: EMAIL_IS_NOT_VERIFIED
Status Code: 401Description: Email address has not been verified.Troubleshooting:
  1. Check your email for verification link
  2. Request a new verification email
  3. Verify email address is correct
  4. Check spam/junk folder

​
403 Forbidden

Access denied due to insufficient permissions.
Error Code: AUTHORIZATION
Status Code: 403Description: You don’t have permission to perform this action.Troubleshooting:
  1. Verify you have the required role/permissions
  2. Check if you’re a member of the project/team
  3. Contact project/team admin to grant access
  4. Ensure you’re accessing the correct resource
Error Code: PERMISSION_DENIED
Status Code: 403Description: Permission denied for the requested operation.Troubleshooting:
  1. Review your user role and permissions
  2. Check project/team access settings
  3. Verify resource ownership
  4. Contact administrator for access
Error Code: DOMAIN_NOT_ALLOWED
Status Code: 403Description: Your email domain is not allowed for this operation.Troubleshooting:
  1. Verify your email domain is whitelisted
  2. Contact administrator to add your domain
  3. Use an allowed email address

​
404 Not Found

Requested resource does not exist.
Error Code: ENTITY_NOT_FOUND
Status Code: 404Description: The requested resource was not found.Common Scenarios:
  • Project not found
  • Agent not found
  • Document not found
  • User not found
Troubleshooting:
  1. Verify the resource ID is correct
  2. Check if the resource was deleted
  3. Ensure you have access to the resource
  4. Verify you’re using the correct project/workspace
Error Code: FILE_NOT_FOUND
Status Code: 404Description: The requested file does not exist.Troubleshooting:
  1. Verify the file ID or path is correct
  2. Check if the file was deleted
  3. Ensure the file is in the expected location
  4. Verify file permissions
Error Code: FLOW_NOT_FOUND
Status Code: 404Description: The requested workflow/flow was not found.Troubleshooting:
  1. Verify the flow ID is correct
  2. Check if the flow was deleted
  3. Ensure you have access to the flow
  4. Verify the flow exists in the current project
Error Code: CONFIG_NOT_FOUND
Status Code: 404Description: Required configuration was not found.Troubleshooting:
  1. Verify configuration exists
  2. Check configuration setup in settings
  3. Ensure required services are configured
  4. Review configuration documentation

​
500 Internal Server Error

Server-side errors that require investigation.
Error Code: ENGINE_OPERATION_FAILURE
Status Code: 500Description: An internal engine operation failed.Troubleshooting:
  1. Retry the request after a few moments
  2. Check system status at status.getodin.ai
  3. If persistent, contact support with error details
  4. Provide error ID if available
Error Code: EXTERNAL_SERVICE
Status Code: 500Description: An external service required for this operation failed.Common Scenarios:
  • LLM provider API failure
  • Third-party integration failure (Google Drive, Slack, etc.)
  • External API timeout
Troubleshooting:
  1. Check external service status
  2. Verify API keys/credentials for external services
  3. Retry the request
  4. Check integration configuration
  5. Contact support if issue persists
Error Code: INFRASTRUCTURE
Status Code: 500Description: Infrastructure error (database, storage, etc.).Troubleshooting:
  1. Retry the request
  2. Check system status
  3. If persistent, contact support
  4. Provide error details and timestamp
Error Code: OPEN_AI_FAILED
Status Code: 500Description: OpenAI API call failed.Troubleshooting:
  1. Check OpenAI service status
  2. Verify API key is valid and has credits
  3. Check rate limits
  4. Retry with exponential backoff
  5. Verify model availability

​
503 Service Unavailable

Service temporarily unavailable.
Error Code: EXECUTION_TIMEOUT
Status Code: 503Description: Operation timed out.Troubleshooting:
  1. Retry the request
  2. Simplify the operation if possible
  3. Check if system is under heavy load
  4. Break down large operations into smaller ones
  5. Contact support if timeout persists

​
Business Logic Errors

Error Code: QUOTA_EXCEEDED
Status Code: 400 or 429Description: You have exceeded your quota limit.Troubleshooting:
  1. Check your current usage in My Account > Dashboard
  2. Review subscription limits
  3. Upgrade your plan if needed
  4. Wait for quota reset period
  5. Contact sales for quota increase
Error Code: FEATURE_DISABLED
Status Code: 400Description: This feature is disabled for your account.Troubleshooting:
  1. Check your subscription plan
  2. Verify feature availability
  3. Upgrade plan if feature requires higher tier
  4. Contact support for feature access
Error Code: FLOW_IN_USE
Status Code: 400Description: The workflow is currently in use and cannot be modified.Troubleshooting:
  1. Wait for active executions to complete
  2. Cancel active workflow runs
  3. Check workflow execution status
  4. Retry after executions complete
Error Code: EXISTING_USER
Status Code: 400Description: User with this email already exists.Troubleshooting:
  1. Try logging in instead of signing up
  2. Use password reset if you forgot credentials
  3. Use a different email address
  4. Contact support if account recovery is needed

​
Integration-Specific Errors

Error Code: INVALID_APP_CONNECTION
Status Code: 400Description: Invalid or expired app connection (OAuth integration).Troubleshooting:
  1. Re-authenticate the integration
  2. Check OAuth token expiration
  3. Verify integration credentials
  4. Reconnect the integration in settings
Error Code: INVALID_SAML_RESPONSE
Status Code: 400Description: Invalid SAML response from SSO provider.Troubleshooting:
  1. Verify SSO configuration
  2. Check SAML metadata URL
  3. Ensure SSO provider is accessible
  4. Contact support for SSO configuration review
Error Code: RATE_LIMITED or ratelimited
Status Code: 429Description: API rate limit exceeded.Troubleshooting:
  1. Wait for rate limit window to reset
  2. Implement exponential backoff
  3. Reduce request frequency
  4. Check rate limit headers in response
  5. Upgrade plan for higher rate limits

​
Getting Help

If you encounter an error that’s not listed here or need assistance:
  1. Check Error Details: Note the error code, message, and error_id
  2. Check System Status: Visit status.getodin.ai for known issues
  3. Review Documentation: Check relevant API documentation
  4. Contact Support: Email Support with:
    • Error code and message
    • Error ID (if available)
    • Steps to reproduce
    • Request/response details (sanitized)
    • Timestamp of the error