​

Common API Errors

​

Error Response Format

{
  "status_code": 400,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "detail": "Additional error details (optional)"
}

• 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

​

VALIDATION_ERROR

• Missing required fields
• Invalid field format (e.g., invalid email, date format)
• Field values outside allowed range
• Invalid data types

{
  "status_code": 400,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "invalid_fields": ["email", "project_id"]
  }
}

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

​

INVALID_API_KEY

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

​

INVALID_CREDENTIALS

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

​

INVALID_OR_EXPIRED_JWT_TOKEN

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

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

​

INVALID_BEARER_TOKEN

1. Verify the token format: Bearer <token>
2. Check if the token has expired
3. Regenerate authentication token
4. Ensure token is not revoked

​

EMAIL_IS_NOT_VERIFIED

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

​

AUTHORIZATION

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

​

PERMISSION_DENIED

1. Review your user role and permissions
2. Check project/team access settings
3. Verify resource ownership
4. Contact administrator for access

​

DOMAIN_NOT_ALLOWED

1. Verify your email domain is whitelisted
2. Contact administrator to add your domain
3. Use an allowed email address

​

404 Not Found

​

ENTITY_NOT_FOUND

• Project not found
• Agent not found
• Document not found
• User not found

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

​

FILE_NOT_FOUND

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

​

FLOW_NOT_FOUND

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

​

CONFIG_NOT_FOUND

1. Verify configuration exists
2. Check configuration setup in settings
3. Ensure required services are configured
4. Review configuration documentation

​

500 Internal Server Error

​

ENGINE_OPERATION_FAILURE

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

​

EXTERNAL_SERVICE

• LLM provider API failure
• Third-party integration failure (Google Drive, Slack, etc.)
• External API timeout

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

​

INFRASTRUCTURE

1. Retry the request
2. Check system status
3. If persistent, contact support
4. Provide error details and timestamp

​

OPEN_AI_FAILED

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

​

EXECUTION_TIMEOUT

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

​

QUOTA_EXCEEDED

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

​

FEATURE_DISABLED

1. Check your subscription plan
2. Verify feature availability
3. Upgrade plan if feature requires higher tier
4. Contact support for feature access

​

FLOW_IN_USE

1. Wait for active executions to complete
2. Cancel active workflow runs
3. Check workflow execution status
4. Retry after executions complete

​

EXISTING_USER

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

​

INVALID_APP_CONNECTION

1. Re-authenticate the integration
2. Check OAuth token expiration
3. Verify integration credentials
4. Reconnect the integration in settings

​

INVALID_SAML_RESPONSE

1. Verify SSO configuration
2. Check SAML metadata URL
3. Ensure SSO provider is accessible
4. Contact support for SSO configuration review

​

RATE_LIMITED

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

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@getodin.ai with:
   • Error code and message
   • Error ID (if available)
   • Steps to reproduce
   • Request/response details (sanitized)
   • Timestamp of the error

​

Additional Resources

• API Reference
• Status Monitoring
• Authentication Guide