API Status Codes

This guide covers HTTP status codes returned by AgentSync APIs and how to handle them appropriately.

Success Codes (2xx)

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
202	Accepted	Request accepted for processing
204	No Content	Request successful, no content to return

200 OK

Standard successful response with data:

{
  "data": {
    "id": "12345",
    "name": "Example Resource",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

201 Created

Resource was successfully created:

{
  "data": {
    "id": "67890",
    "name": "New Resource",
    "created_at": "2024-01-15T10:30:00Z"
  },
  "links": {
    "self": "/v1/resources/67890"
  }
}

204 No Content

Successful operation with no response body (common for DELETE operations).

Client Error Codes (4xx)

Code	Status	Description
400	Bad Request	Invalid request syntax or parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Authenticated but not authorized
404	Not Found	Resource does not exist
409	Conflict	Request conflicts with current state
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded

400 Bad Request

Invalid request format or parameters:

{
  "error": "bad_request",
  "error_description": "Invalid JSON in request body",
  "details": {
    "field": "email",
    "issue": "Invalid email format"
  }
}

401 Unauthorized

Authentication is missing or invalid:

{
  "error": "unauthorized",
  "error_description": "Invalid or expired access token"
}

How to handle:

Check if the access token is valid
Refresh the token if expired
Verify credentials are correct

403 Forbidden

Authenticated but lacks permission:

{
  "error": "forbidden",
  "error_description": "You do not have permission to access this resource"
}

How to handle:

Verify you have the required permissions
Contact DevOps if you need additional access

404 Not Found

Resource does not exist:

{
  "error": "not_found",
  "error_description": "Resource with ID '12345' not found"
}

How to handle:

Verify the resource ID is correct
Check if the resource was deleted
Ensure you're using the correct environment

409 Conflict

Request conflicts with current state:

{
  "error": "conflict",
  "error_description": "A resource with this identifier already exists"
}

422 Unprocessable Entity

Validation errors:

{
  "error": "validation_error",
  "error_description": "Request validation failed",
  "details": [
    {
      "field": "email",
      "message": "Email is required"
    },
    {
      "field": "phone",
      "message": "Invalid phone number format"
    }
  ]
}

429 Too Many Requests

Rate limit exceeded:

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests",
  "retry_after": 45
}

See Rate Limits for handling strategies.

Server Error Codes (5xx)

Code	Status	Description
500	Internal Server Error	Unexpected server error
502	Bad Gateway	Upstream service error
503	Service Unavailable	Service temporarily unavailable
504	Gateway Timeout	Upstream service timeout

500 Internal Server Error

Unexpected server error:

{
  "error": "internal_error",
  "error_description": "An unexpected error occurred",
  "request_id": "req-abc123"
}

How to handle:

Retry with exponential backoff
Report persistent errors to DevOps with the request_id

503 Service Unavailable

Service is temporarily unavailable:

{
  "error": "service_unavailable",
  "error_description": "Service is under maintenance",
  "retry_after": 300
}

How to handle:

Check status.agentsync.io for updates
Retry after the indicated time

Error Handling Example

import requests
import time

def handle_response(response):
    if response.status_code == 200:
        return response.json()

    elif response.status_code == 401:
        raise AuthenticationError("Token expired or invalid")

    elif response.status_code == 403:
        raise PermissionError("Access denied")

    elif response.status_code == 404:
        raise NotFoundError("Resource not found")

    elif response.status_code == 422:
        errors = response.json().get("details", [])
        raise ValidationError(f"Validation failed: {errors}")

    elif response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 60))
        raise RateLimitError(f"Rate limited. Retry after {retry_after}s")

    elif response.status_code >= 500:
        request_id = response.json().get("request_id", "unknown")
        raise ServerError(f"Server error. Request ID: {request_id}")

    else:
        raise APIError(f"Unexpected status: {response.status_code}")

Best Practices

Always check status codes - Don't assume success
Parse error responses - Extract useful error details
Log request IDs - Include in error reports for debugging
Implement retries - For 5xx errors and rate limits
Handle gracefully - Provide meaningful feedback to users

Need help with error handling? Contact #devops-support on Slack.