Common API Errors

This article will help you understand the most common API errors that may be encountered when utilizing EKB'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.

VALIDATION_ERROR

Error Code: VALIDATION_ERROR Status Code: 400

Description: 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:

Review the invalid_fields array to identify problematic fields
Check field requirements in the API documentation
Verify data types match expected formats
Ensure all required fields are provided

INVALID_API_KEY

Error Code: INVALID_API_KEY
Status Code: 400

Description: The provided API key is invalid or malformed.

Troubleshooting:

Verify the API key is correctly copied (no extra spaces)
Check if the API key is active in My Account > API Keys
Ensure you're using the correct API key for your environment
Regenerate the API key if necessary

INVALID_CREDENTIALS

Error Code: INVALID_CREDENTIALS
Status Code: 400

Description: Authentication credentials are invalid.

Troubleshooting:

Verify email and password are correct
Check if account is locked or disabled
Try resetting your password
Ensure you're using the correct authentication method

INVALID_OR_EXPIRED_JWT_TOKEN

Error Code: INVALID_OR_EXPIRED_JWT_TOKEN
Status Code: 400

Description: The JWT token is invalid, expired, or malformed.

Troubleshooting:

Refresh your authentication token
Log out and log back in
Check token expiration time
Verify token is being sent in the correct header format

401 Unauthorized

Authentication required or authentication failed.

AUTHENTICATION

Error Code: AUTHENTICATION
Status Code: 401

Description: Authentication is required to access this resource.

Troubleshooting:

Ensure you're logged in
Check if your session has expired
Verify authentication headers are included in the request
Re-authenticate if necessary

INVALID_BEARER_TOKEN

Error Code: INVALID_BEARER_TOKEN
Status Code: 401

Description: The Bearer token provided is invalid.

Troubleshooting:

Verify the token format: Bearer <token>
Check if the token has expired
Regenerate authentication token
Ensure token is not revoked

EMAIL_IS_NOT_VERIFIED

Error Code: EMAIL_IS_NOT_VERIFIED
Status Code: 401

Description: Email address has not been verified.

Troubleshooting:

Check your email for verification link
Request a new verification email
Verify email address is correct
Check spam/junk folder

403 Forbidden

Access denied due to insufficient permissions.

AUTHORIZATION

Error Code: AUTHORIZATION
Status Code: 403

Description: You don't have permission to perform this action.

Troubleshooting:

Verify you have the required role/permissions
Check if you're a member of the project/team
Contact project/team admin to grant access
Ensure you're accessing the correct resource

PERMISSION_DENIED

Error Code: PERMISSION_DENIED
Status Code: 403

Description: Permission denied for the requested operation.

Troubleshooting:

Review your user role and permissions
Check project/team access settings
Verify resource ownership
Contact administrator for access

DOMAIN_NOT_ALLOWED

Error Code: DOMAIN_NOT_ALLOWED
Status Code: 403

Description: Your email domain is not allowed for this operation.

Troubleshooting:

Verify your email domain is whitelisted
Contact administrator to add your domain
Use an allowed email address

404 Not Found

Requested resource does not exist.

ENTITY_NOT_FOUND

Error Code: ENTITY_NOT_FOUND
Status Code: 404

Description: The requested resource was not found.

Common Scenarios:

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

Troubleshooting:

Verify the resource ID is correct
Check if the resource was deleted
Ensure you have access to the resource
Verify you're using the correct project/workspace

FILE_NOT_FOUND

Error Code: FILE_NOT_FOUND
Status Code: 404

Description: The requested file does not exist.

Troubleshooting:

Verify the file ID or path is correct
Check if the file was deleted
Ensure the file is in the expected location
Verify file permissions

FLOW_NOT_FOUND

Error Code: FLOW_NOT_FOUND
Status Code: 404

Description: The requested workflow/flow was not found.

Troubleshooting:

Verify the flow ID is correct
Check if the flow was deleted
Ensure you have access to the flow
Verify the flow exists in the current project

CONFIG_NOT_FOUND

Error Code: CONFIG_NOT_FOUND
Status Code: 404

Description: Required configuration was not found.

Troubleshooting:

Verify configuration exists
Check configuration setup in settings
Ensure required services are configured
Review configuration documentation

500 Internal Server Error

Server-side errors that require investigation.

ENGINE_OPERATION_FAILURE

Error Code: ENGINE_OPERATION_FAILURE
Status Code: 500

Description: An internal engine operation failed.

Troubleshooting:

Retry the request after a few moments
Check system status at status.getodin.ai
If persistent, contact support with error details
Provide error ID if available

EXTERNAL_SERVICE

Error Code: EXTERNAL_SERVICE
Status Code: 500

Description: 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:

Check external service status
Verify API keys/credentials for external services
Retry the request
Check integration configuration
Contact support if issue persists

INFRASTRUCTURE

Error Code: INFRASTRUCTURE
Status Code: 500

Description: Infrastructure error (database, storage, etc.).

Troubleshooting:

Retry the request
Check system status
If persistent, contact support
Provide error details and timestamp

OPEN_AI_FAILED

Error Code: OPEN_AI_FAILED
Status Code: 500

Description: OpenAI API call failed.

Troubleshooting:

Check OpenAI service status
Verify API key is valid and has credits
Check rate limits
Retry with exponential backoff
Verify model availability

503 Service Unavailable

Service temporarily unavailable.

EXECUTION_TIMEOUT

Error Code: EXECUTION_TIMEOUT
Status Code: 503

Description: Operation timed out.

Troubleshooting:

Retry the request
Simplify the operation if possible
Check if system is under heavy load
Break down large operations into smaller ones
Contact support if timeout persists

Business Logic Errors

QUOTA_EXCEEDED

Error Code: QUOTA_EXCEEDED
Status Code: 400 or 429

Description: You have exceeded your quota limit.

Troubleshooting:

Check your current usage in My Account > Dashboard
Review subscription limits
Upgrade your plan if needed
Wait for quota reset period
Contact sales for quota increase

FEATURE_DISABLED

Error Code: FEATURE_DISABLED
Status Code: 400

Description: This feature is disabled for your account.

Troubleshooting:

Check your subscription plan
Verify feature availability
Upgrade plan if feature requires higher tier
Contact support for feature access

FLOW_IN_USE

Error Code: FLOW_IN_USE
Status Code: 400

Description: The workflow is currently in use and cannot be modified.

Troubleshooting:

Wait for active executions to complete
Cancel active workflow runs
Check workflow execution status
Retry after executions complete

EXISTING_USER

Error Code: EXISTING_USER
Status Code: 400

Description: User with this email already exists.

Troubleshooting:

Try logging in instead of signing up
Use password reset if you forgot credentials
Use a different email address
Contact support if account recovery is needed

Integration-Specific Errors

INVALID_APP_CONNECTION

Error Code: INVALID_APP_CONNECTION
Status Code: 400

Description: Invalid or expired app connection (OAuth integration).

Troubleshooting:

Re-authenticate the integration
Check OAuth token expiration
Verify integration credentials
Reconnect the integration in settings

INVALID_SAML_RESPONSE

Error Code: INVALID_SAML_RESPONSE
Status Code: 400

Description: Invalid SAML response from SSO provider.

Troubleshooting:

Verify SSO configuration
Check SAML metadata URL
Ensure SSO provider is accessible
Contact support for SSO configuration review

RATE_LIMITED

Error Code: RATE_LIMITED or ratelimited
Status Code: 429

Description: API rate limit exceeded.

Troubleshooting:

Wait for rate limit window to reset
Implement exponential backoff
Reduce request frequency
Check rate limit headers in response
Upgrade plan for higher rate limits

Getting Help

If you encounter an error that's not listed here or need assistance:

Check Error Details: Note the error code, message, and error_id
Check System Status: Visit status.getodin.ai for known issues
Review Documentation: Check relevant API documentation
Contact Support: Email Support with:
- Error code and message
- Error ID (if available)
- Steps to reproduce
- Request/response details (sanitized)
- Timestamp of the error

Error Response Format​

HTTP Status Codes​

400 Bad Request​

401 Unauthorized​

403 Forbidden​

404 Not Found​

500 Internal Server Error​

503 Service Unavailable​

Business Logic Errors​

Integration-Specific Errors​

Getting Help​

Error Response Format

HTTP Status Codes

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

500 Internal Server Error

503 Service Unavailable

Business Logic Errors

Integration-Specific Errors

Getting Help