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

HTTP Status Codes
Error Response Formats
Error Code Reference
Troubleshooting Guide
Error Examples
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:

Check that the Authorization: Bearer <token> header is present
Verify the token is not expired
Refresh the token using /api/auth/refresh
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:

Verify you have the required permissions
Check organization membership
Contact organization admin for access
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:

Verify the resource ID is correct
Check that the resource exists
Verify you have access to the resource
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:

Reduce file size
Use chunked upload for large files
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:

Wait for the specified retry period
Implement exponential backoff
Reduce request frequency
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:

Retry the request after a short delay
Check API status page
Contact support if issue persists
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:

Wait and retry after a delay
Check service status
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:

Retry the request
Reduce request complexity
Check network connectivity
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., user@example.com)

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:

Verify email and password are correct
Check for typos (email is case-insensitive, but password is case-sensitive)
Use password reset if forgotten: /api/auth/request-password-reset
Check email for password setup link if account is new
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:

Implement automatic token refresh before expiration
Refresh token when receiving 401 responses
Re-authenticate if refresh token expired
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:

Include Authorization: Bearer <token> header
Verify header format is correct (space after "Bearer")
Check token is stored and retrieved correctly
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:

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

Common Validation Issues

Issue: "Missing required field"

Solutions:

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

Issue: "Password validation failed"

Solutions:

Review error details array for specific requirements
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
Use password strength checker

Issue: "Invalid URL format"

Solutions:

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

Issue: "Duplicate resource name"

Solutions:

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

Common MCP Issues

Issue: "Server not found"

Solutions:

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

Issue: "Connection failed" when adding MCP server

Solutions:

Verify server URL is correct and accessible
Check server is running and responding
Verify network connectivity to server
Check server supports MCP protocol
Verify authentication if server requires it
Check server logs for errors

Issue: "Access denied" for MCP server

Solutions:

Verify server ownership or public access
Check agent sharing settings
Verify organization membership if server is organization-shared
Contact server owner for access

Issue: "MCP not enabled for this agent"

Solutions:

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

Rate Limiting Issues

Issue: "Rate limit exceeded"

Solutions:

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

Network and Connectivity Issues

Issue: "Request timed out"

Solutions:

Check network connectivity
Verify server is accessible
Retry request (may be temporary)
Reduce request size/complexity
Check firewall/proxy settings
Contact support if persistent

Issue: "Service unavailable"

Solutions:

Check API status page
Wait and retry after delay
Implement retry logic with exponential backoff
Check service maintenance schedule
Contact support if issue persists

Issue: "Internal server error"

Solutions:

Verify request format is correct
Retry request (may be temporary)
Check if issue is specific to your request
Contact support with request details if persistent
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": "user@example.com", "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": "user@example.com",
    "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

Check HTTP Status Code: Indicates error category
- 4xx: Client error (your request)
- 5xx: Server error (API issue)
Read Error Message: Provides specific error information
Check Error Details: Some errors include details array with specific issues
Verify Request Format: Compare your request to API documentation
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

Verify Authentication:
- Check token is valid and not expired
- Verify Authorization header format
- Test with /api/auth/heartbeat endpoint
Validate Request Format:
- Check JSON structure is valid
- Verify all required fields are present
- Ensure field types match expected types
Check Network:
- Verify connectivity to API
- Check firewall/proxy settings
- Test with curl to isolate client issues
Review Error Details:
- Read full error message
- Check details array for specific issues
- Compare to API documentation
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:

Error Details:
- HTTP status code
- Full error response body
- Request URL and method
Request Information:
- Request headers (sanitize tokens)
- Request body
- Timestamp of request
Context:
- What you were trying to do
- Steps to reproduce
- Expected vs actual behavior
Environment:
- API endpoint used
- Client library/version
- Any relevant configuration

Support Contact:

Email: support@agent700.ai

Related Documentation

Authentication Guide - Comprehensive authentication documentation
OpenAPI Specification - Complete API reference with error schemas
MCP Security Setup - MCP service error handling

Last Updated: January 2025
API Version: 1.0.0