API Reference
Start typing to search…

Error Handeling

Agent700 API Error Handling Guide

Overview

This guide provides comprehensive information about error handling in the Agent700 Platform API, including HTTP status codes, error response formats, error codes, troubleshooting, and debugging tips.

Base URL: https://api.agent700.ai/api

Table of Contents

  1. HTTP Status Codes
  2. Error Response Formats
  3. Error Code Reference
  4. Troubleshooting Guide
  5. Error Examples
  6. Debugging Tips

HTTP Status Codes

The Agent700 API uses standard HTTP status codes to indicate the result of API requests.

200 OK

Meaning: Request succeeded.

When it occurs:

  • Successful GET, PUT, PATCH, DELETE requests
  • Successful authentication
  • Successful resource creation/update

Example Response:

{
  "message": "OK"
}

201 Created

Meaning: Resource created successfully.

When it occurs:

  • New agent created
  • New organization created
  • New app password created

Example Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "My Agent",
  "createdAt": "2025-01-15T10:00:00Z"
}

400 Bad Request

Meaning: Request is invalid or malformed.

Common causes:

  • Missing required fields
  • Invalid field formats
  • Validation errors
  • Invalid URL format
  • Duplicate resource names
  • Invalid request body structure

Example Responses:

{
  "error": "Missing required field: name"
}
{
  "error": "Email and password are required"
}
{
  "error": "Invalid URL format"
}
{
  "error": "Password validation failed",
  "details": [
    "Password must be at least 12 characters long",
    "Password must contain at least one uppercase letter"
  ]
}

401 Unauthorized

Meaning: Authentication required or authentication failed.

Common causes:

  • Missing Authorization header
  • Invalid or expired access token
  • Invalid credentials
  • Token refresh failed
  • App password expired or revoked

Example Responses:

{
  "error": "Authentication required"
}
{
  "error": "Invalid credentials"
}
{
  "error": "Invalid app password token"
}

How to resolve:

  1. Check that the Authorization: Bearer <token> header is present
  2. Verify the token is not expired
  3. Refresh the token using /api/auth/refresh
  4. Re-authenticate if token refresh fails

403 Forbidden

Meaning: Authenticated but not authorized to perform the action.

Common causes:

  • Insufficient permissions
  • Access denied to resource
  • Organization membership required
  • Admin/billing owner role required
  • MCP not enabled for agent
  • Model does not support requested feature

Example Responses:

{
  "error": "Access denied"
}
{
  "error": "You do not belong to this organization"
}
{
  "error": "Only admins or billing owners can add users to organizations"
}
{
  "error": "MCP is not enabled for this agent"
}
{
  "error": "MCP is only supported by OpenAI and Claude models. Current model: sonar-pro"
}

How to resolve:

  1. Verify you have the required permissions
  2. Check organization membership
  3. Contact organization admin for access
  4. Verify resource ownership

404 Not Found

Meaning: Requested resource does not exist.

Common causes:

  • Resource ID doesn't exist
  • Resource was deleted
  • Invalid endpoint URL
  • User not found
  • Organization not found
  • Agent not found

Example Responses:

{
  "error": "Agent not found or access denied"
}
{
  "error": "User not found"
}
{
  "error": "Organization not found"
}
{
  "error": "Rating not found"
}
{
  "error": "Server not found"
}

How to resolve:

  1. Verify the resource ID is correct
  2. Check that the resource exists
  3. Verify you have access to the resource
  4. Check the endpoint URL

413 Payload Too Large

Meaning: Request payload exceeds size limits.

Common causes:

  • File upload too large
  • URL content too large
  • Request body exceeds limits

Example Responses:

{
  "error": "URL content too large"
}

How to resolve:

  1. Reduce file size
  2. Use chunked upload for large files
  3. Compress content if possible

429 Too Many Requests

Meaning: Rate limit exceeded.

Common causes:

  • Too many requests in short time period
  • App password rate limit exceeded
  • API rate limit exceeded

Example Responses:

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

How to resolve:

  1. Wait for the specified retry period
  2. Implement exponential backoff
  3. Reduce request frequency
  4. Check rate limit headers in response

500 Internal Server Error

Meaning: Server encountered an unexpected error.

Common causes:

  • Database connection issues
  • External service failures
  • Internal processing errors
  • Configuration problems

Example Responses:

{
  "error": "Internal server error"
}
{
  "error": "Failed to create user: Database connection error"
}

How to resolve:

  1. Retry the request after a short delay
  2. Check API status page
  3. Contact support if issue persists
  4. Verify request format is correct

503 Service Unavailable

Meaning: Service temporarily unavailable.

Common causes:

  • Maintenance mode
  • Service overload
  • MCP service not healthy
  • Database unavailable

Example Responses:

{
  "success": false,
  "error": "MCP service is not healthy"
}

How to resolve:

  1. Wait and retry after a delay
  2. Check service status
  3. Implement retry logic with exponential backoff

504 Gateway Timeout

Meaning: Request timed out.

Common causes:

  • External service timeout
  • Long-running operation exceeded timeout
  • Network connectivity issues

Example Responses:

{
  "error": "Request timed out"
}

How to resolve:

  1. Retry the request
  2. Reduce request complexity
  3. Check network connectivity
  4. Contact support if persistent

Error Response Formats

The Agent700 API uses different error response formats depending on the endpoint and error type.

Standard ErrorResponse

Used by most endpoints for error responses.

Schema:

{
  "error": "string"
}

Example:

{
  "error": "Missing required field: name"
}

AuthErrorResponse

Used by authentication endpoints with optional details array.

Schema:

{
  "error": "string",
  "details": ["string"]
}

Example:

{
  "error": "Password validation failed",
  "details": [
    "Password must be at least 12 characters long",
    "Password must contain at least one uppercase letter",
    "Password must contain at least one number"
  ]
}

MCP ErrorResponse

Used by MCP endpoints with success field.

Schema:

{
  "success": false,
  "error": "string"
}

Example:

{
  "success": false,
  "error": "Server not found"
}

Streaming Error Format

Used in Server-Sent Events (SSE) and WebSocket streaming.

Format:

{
  "error": "string"
}

Example:

{
  "error": "Service temporarily unavailable"
}

Note: Streaming errors are sanitized for security. Admin users receive full error details, while regular users receive generic messages.

Error Code Reference

Authentication Errors

Invalid Credentials

  • Status: 401
  • Error: "Invalid credentials"
  • Cause: Email/password combination is incorrect
  • Resolution: Verify email and password, check for typos

Missing Token

  • Status: 401
  • Error: "Authentication required"
  • Cause: Authorization header missing or invalid format
  • Resolution: Include Authorization: Bearer <token> header

Expired Token

  • Status: 401
  • Error: "Token expired" or "Unauthorized"
  • Cause: Access token has expired
  • Resolution: Refresh token using /api/auth/refresh

Invalid App Password

  • Status: 401
  • Error: "Invalid app password token" or "Invalid app password token format"
  • Cause: App password is invalid, expired, or revoked
  • Resolution: Verify app password format (app_a7_ prefix), check expiration, create new app password if needed

Token Refresh Failed

  • Status: 401
  • Error: "No refresh token provided" or "Refresh token validation failed"
  • Cause: Refresh token missing, expired, or invalid
  • Resolution: Re-authenticate via login endpoint

Validation Errors

Missing Required Fields

  • Status: 400
  • Error: "Missing required field: <field_name>"
  • Common fields: name, email, password, url, organizationId
  • Resolution: Include all required fields in request body

Invalid Email Format

  • Status: 400
  • Error: "Invalid email format"
  • Resolution: Use valid email address format (e.g., [email protected])

Password Validation Failed

  • Status: 400
  • Error: "Password validation failed"
  • Details: Array of specific validation errors
  • Common issues:
    • Password too short (minimum 12 characters)
    • Missing uppercase letter
    • Missing lowercase letter
    • Missing number
    • Missing special character
    • Password contains email
  • Resolution: Follow password requirements in error details

Invalid URL Format

  • Status: 400
  • Error: "Invalid URL format"
  • Resolution: Use valid HTTP/HTTPS URL (e.g., https://example.com)

Duplicate Resource

  • Status: 400
  • Error: "Server name \"<name>\" already exists" or "Email already registered"
  • Resolution: Use unique name/identifier or update existing resource

Field Too Long

  • Status: 400
  • Error: "Server name too long (max 50 characters)" or similar
  • Resolution: Reduce field length to meet maximum requirements

Authorization Errors

Access Denied

  • Status: 403
  • Error: "Access denied"
  • Cause: User lacks permission for the requested action
  • Resolution: Verify permissions, contact organization admin

Organization Membership Required

  • Status: 403
  • Error: "You do not belong to this organization"
  • Resolution: Join the organization or request access

Admin Role Required

  • Status: 403
  • Error: "Only admins or billing owners can <action>"
  • Resolution: Request admin role or contact organization admin

MCP Not Enabled

  • Status: 403
  • Error: "MCP is not enabled for this agent"
  • Resolution: Enable MCP for the agent

Model Not Supported

  • Status: 403
  • Error: "MCP is only supported by OpenAI and Claude models. Current model: <model>"
  • Resolution: Change agent model to supported model

Resource Errors

Resource Not Found

  • Status: 404
  • Error: "<Resource> not found" (e.g., "Agent not found", "User not found")
  • Resolution: Verify resource ID, check resource exists, verify access

Server Not Found

  • Status: 404
  • Error: "Server not found" or "Server with ID \"<id>\" not found"
  • Resolution: Verify server ID, check server exists, verify ownership

User Not in Organization

  • Status: 404
  • Error: "User not found in any organization" or "User is not a member of this organization"
  • Resolution: Add user to organization or verify membership

MCP-Specific Errors

Server Connection Failed

  • Status: 200 (with warning) or 500
  • Error: "Server added but connection failed: <reason>"
  • Common reasons: Connection timeout, invalid URL, server unreachable
  • Resolution: Verify server URL, check server is running, verify network connectivity

Missing MCP Fields

  • Status: 400
  • Error: "Missing required fields: tool_name and one of server_id or server_name"
  • Resolution: Include required fields in request

Server Name Already Exists

  • Status: 400
  • Error: "Server name \"<name>\" already exists for this agent"
  • Resolution: Use unique server name

Rate Limiting Errors

Rate Limit Exceeded

  • Status: 429
  • Error: "Rate limit exceeded"
  • Additional fields: retry_after (seconds)
  • Resolution: Wait for retry period, implement exponential backoff

Network Errors

Request Timeout

  • Status: 504
  • Error: "Request timed out"
  • Resolution: Retry request, reduce request complexity, check network

Too Many Redirects

  • Status: 400
  • Error: "Too many redirects"
  • Resolution: Verify URL, check redirect chain

SSL Verification Failed

  • Status: 400
  • Error: "SSL verification failed"
  • Resolution: Verify SSL certificate, check URL validity

Unable to Fetch URL

  • Status: 500
  • Error: "Unable to fetch the URL"
  • Resolution: Verify URL is accessible, check network connectivity

Troubleshooting Guide

Common Authentication Issues

Issue: "Invalid credentials" on login

Possible causes:

  • Incorrect email or password
  • Account not set up (password setup not completed)
  • Account locked or disabled

Solutions:

  1. Verify email and password are correct
  2. Check for typos (email is case-insensitive, but password is case-sensitive)
  3. Use password reset if forgotten: /api/auth/request-password-reset
  4. Check email for password setup link if account is new
  5. Contact support if account appears locked

Issue: "Token expired" errors

Possible causes:

  • Access token expired (default: 8 hours)
  • Refresh token expired (default: 7 days)
  • Token refresh failed

Solutions:

  1. Implement automatic token refresh before expiration
  2. Refresh token when receiving 401 responses
  3. Re-authenticate if refresh token expired
  4. Check token expiration times in response (expiresIn field)

Issue: "Missing token" or "Authentication required"

Possible causes:

  • Authorization header missing
  • Invalid header format
  • Token not included in request

Solutions:

  1. Include Authorization: Bearer <token> header
  2. Verify header format is correct (space after "Bearer")
  3. Check token is stored and retrieved correctly
  4. Verify token is not null or empty

Issue: App password authentication fails

Possible causes:

  • Invalid app password format
  • App password expired or revoked
  • App password locked due to failed attempts
  • Rate limit exceeded

Solutions:

  1. Verify app password format: app_a7_ + 32 hex characters
  2. Check app password expiration date
  3. Verify app password is active (not revoked)
  4. Wait if rate limited, then retry
  5. Create new app password if needed

Common Validation Issues

Issue: "Missing required field"

Solutions:

  1. Review API documentation for required fields
  2. Check request body includes all required fields
  3. Verify field names match exactly (case-sensitive)
  4. Check JSON structure is valid

Issue: "Password validation failed"

Solutions:

  1. Review error details array for specific requirements
  2. Ensure password meets all criteria:
    • Minimum 12 characters
    • At least one uppercase letter
    • At least one lowercase letter
    • At least one number
    • At least one special character
    • Does not contain email address
  3. Use password strength checker

Issue: "Invalid URL format"

Solutions:

  1. Ensure URL includes scheme (http:// or https://)
  2. Verify URL is properly formatted
  3. Check for special characters that need encoding
  4. Validate URL before sending request

Issue: "Duplicate resource name"

Solutions:

  1. Use unique name for resource
  2. Check existing resources for name conflicts
  3. Update existing resource instead of creating duplicate
  4. Delete old resource if no longer needed

Common MCP Issues

Issue: "Server not found"

Solutions:

  1. Verify server ID or name is correct
  2. Check server exists and is accessible
  3. Verify you have access to the server (ownership, public, or shared)
  4. List servers to see available servers

Issue: "Connection failed" when adding MCP server

Solutions:

  1. Verify server URL is correct and accessible
  2. Check server is running and responding
  3. Verify network connectivity to server
  4. Check server supports MCP protocol
  5. Verify authentication if server requires it
  6. Check server logs for errors

Issue: "Access denied" for MCP server

Solutions:

  1. Verify server ownership or public access
  2. Check agent sharing settings
  3. Verify organization membership if server is organization-shared
  4. Contact server owner for access

Issue: "MCP not enabled for this agent"

Solutions:

  1. Enable MCP in agent settings
  2. Verify agent uses supported model (OpenAI or Claude)
  3. Check agent configuration

Rate Limiting Issues

Issue: "Rate limit exceeded"

Solutions:

  1. Check retry_after field in error response
  2. Wait for specified time before retrying
  3. Implement exponential backoff
  4. Reduce request frequency
  5. Use app passwords for higher rate limits (if applicable)
  6. Contact support for rate limit increase if needed

Network and Connectivity Issues

Issue: "Request timed out"

Solutions:

  1. Check network connectivity
  2. Verify server is accessible
  3. Retry request (may be temporary)
  4. Reduce request size/complexity
  5. Check firewall/proxy settings
  6. Contact support if persistent

Issue: "Service unavailable"

Solutions:

  1. Check API status page
  2. Wait and retry after delay
  3. Implement retry logic with exponential backoff
  4. Check service maintenance schedule
  5. Contact support if issue persists

Issue: "Internal server error"

Solutions:

  1. Verify request format is correct
  2. Retry request (may be temporary)
  3. Check if issue is specific to your request
  4. Contact support with request details if persistent
  5. Check API status for known issues

Error Examples

Authentication Error Examples

Invalid Credentials

curl -X POST https://api.agent700.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "wrongpassword"}'

Response (401):

{
  "error": "Invalid credentials"
}

Expired Token

curl -X GET https://api.agent700.ai/api/agents \
  -H "Authorization: Bearer expired-token-here"

Response (401):

{
  "error": "Unauthorized"
}

Missing Token

curl -X GET https://api.agent700.ai/api/agents

Response (401):

{
  "error": "Authentication required"
}

Validation Error Examples

Missing Required Field

curl -X POST https://api.agent700.ai/api/agents \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4"}'

Response (400):

{
  "error": "Missing required field: name"
}

Password Validation Failed

curl -X POST https://api.agent700.ai/api/auth/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "short"
  }'

Response (400):

{
  "error": "Password validation failed",
  "details": [
    "Password must be at least 12 characters long",
    "Password must contain at least one uppercase letter",
    "Password must contain at least one number"
  ]
}

Invalid URL Format

curl -X POST https://api.agent700.ai/api/mcp/servers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-server",
    "url": "not-a-valid-url"
  }'

Response (400):

{
  "success": false,
  "error": "Invalid URL format"
}

Authorization Error Examples

Access Denied

curl -X DELETE https://api.agent700.ai/api/agents/other-users-agent-id \
  -H "Authorization: Bearer <token>"

Response (403):

{
  "error": "Access denied"
}

Organization Membership Required

curl -X POST https://api.agent700.ai/api/organizations/org-id/users \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-id"}'

Response (403):

{
  "error": "You do not belong to this organization"
}

Resource Error Examples

Resource Not Found

curl -X GET https://api.agent700.ai/api/agents/non-existent-id \
  -H "Authorization: Bearer <token>"

Response (404):

{
  "error": "Agent not found or access denied"
}

Rate Limiting Error Example

Rate Limit Exceeded

# After making too many requests quickly
curl -X POST https://api.agent700.ai/api/auth/app-login \
  -H "Content-Type: application/json" \
  -d '{"token": "app_a7_..."}'

Response (429):

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

MCP Error Examples

Server Connection Failed

curl -X POST https://api.agent700.ai/api/agents/agent-id/mcp/servers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-server",
    "url": "https://unreachable-server.com"
  }'

Response (200 with warning):

{
  "success": true,
  "message": "Server \"my-server\" added successfully for agent",
  "server": {
    "name": "my-server",
    "url": "https://unreachable-server.com",
    "status": "disconnected",
    "tools_count": 0,
    "resources_count": 0
  },
  "warning": "Server added but connection failed: Connection timeout"
}

MCP Not Enabled

curl -X POST https://api.agent700.ai/api/agents/agent-id/mcp/servers \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-server",
    "url": "https://mcp.example.com"
  }'

Response (403):

{
  "success": false,
  "error": "MCP is not enabled for this agent"
}

Debugging Tips

How to Read Error Responses

  1. Check HTTP Status Code: Indicates error category

    • 4xx: Client error (your request)
    • 5xx: Server error (API issue)

  2. Read Error Message: Provides specific error information

  3. Check Error Details: Some errors include details array with specific issues

  4. Verify Request Format: Compare your request to API documentation

  5. Check Response Headers: May include rate limit info, retry times, etc.

Logging and Monitoring

Client-Side Logging

try {
  const response = await fetch(url, options);
  
  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', {
      status: response.status,
      statusText: response.statusText,
      error: error,
      url: url,
      timestamp: new Date().toISOString()
    });
  }
  
  return response.json();
} catch (error) {
  console.error('Request failed:', error);
  throw error;
}

Python Logging

import logging
import requests

logger = logging.getLogger(__name__)

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    return response.json()
except requests.exceptions.HTTPError as e:
    logger.error(f'API Error: {e.response.status_code} - {e.response.text}')
    raise
except requests.exceptions.RequestException as e:
    logger.error(f'Request failed: {e}')
    raise

Common Debugging Steps

  1. Verify Authentication:

    • Check token is valid and not expired
    • Verify Authorization header format
    • Test with /api/auth/heartbeat endpoint

  2. Validate Request Format:

    • Check JSON structure is valid
    • Verify all required fields are present
    • Ensure field types match expected types

  3. Check Network:

    • Verify connectivity to API
    • Check firewall/proxy settings
    • Test with curl to isolate client issues

  4. Review Error Details:

    • Read full error message
    • Check details array for specific issues
    • Compare to API documentation

  5. Test with Minimal Request:

    • Start with simplest valid request
    • Add fields incrementally
    • Identify which field causes error

Error Response Headers

Check response headers for additional information:

  • Retry-After: Seconds to wait before retrying (rate limiting)
  • X-RateLimit-Limit: Maximum requests per window
  • X-RateLimit-Remaining: Remaining requests in window
  • X-RateLimit-Reset: Timestamp when rate limit resets

Contacting Support

When contacting support, include:

  1. Error Details:

    • HTTP status code
    • Full error response body
    • Request URL and method

  2. Request Information:

    • Request headers (sanitize tokens)
    • Request body
    • Timestamp of request

  3. Context:

    • What you were trying to do
    • Steps to reproduce
    • Expected vs actual behavior

  4. Environment:

    • API endpoint used
    • Client library/version
    • Any relevant configuration

Support Contact:

Related Documentation

Last Updated: January 2025
API Version: 1.0.0