---
title: "API Status Codes"
description: "This guide covers HTTP status codes returned by AgentSync APIs and how to handle them appropriately."
url: "https://internal-developer-portal.agentsync.io/api-status-codes"
image: "https://internal-developer-portal.agentsync.io/_og/d/c_Ocean.takumi,title_API+Status+Codes,description_This+guide+covers+HTTP+status+codes+returned+by+AgentSync+APIs+and+how+to+handle+them+appropriately.,props_eyJ0aGVtZSI6eyJjb2xvcnMiOnt9fX0,p_Ii9hcGktc3RhdHVzLWNvZGVzIg,s_YKM7JyljIjugjDkO.png"
---

# API Status Codes

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

## [Success Codes (2xx)](#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](#_200-ok)

Standard successful response with data:

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

### [201 Created](#_201-created)

Resource was successfully created:

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

### [204 No Content](#_204-no-content)

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

## [Client Error Codes (4xx)](#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](#_400-bad-request)

Invalid request format or parameters:

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

### [401 Unauthorized](#_401-unauthorized)

Authentication is missing or invalid:

```json
{
  "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](#_403-forbidden)

Authenticated but lacks permission:

```json
{
  "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](#_404-not-found)

Resource does not exist:

```json
{
  "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](#_409-conflict)

Request conflicts with current state:

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

### [422 Unprocessable Entity](#_422-unprocessable-entity)

Validation errors:

```json
{
  "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](#_429-too-many-requests)

Rate limit exceeded:

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

See [Rate Limits](https://internal-developer-portal.agentsync.io/api-rate-limits) for handling strategies.

## [Server Error Codes (5xx)](#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](#_500-internal-server-error)

Unexpected server error:

```json
{
  "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](#_503-service-unavailable)

Service is temporarily unavailable:

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

**How to handle:**

-   Check [status.agentsync.io](https://status.agentsync.io) for updates
-   Retry after the indicated time

## [Error Handling Example](#error-handling-example)

```python
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](#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.