---
title: "API Status Codes"
description: "Branch on the HTTP status code — and on code where v2 provides it — rather than parsing message text. Exact error shapes vary by endpoint and scenario."
url: "https://developer.agentsync.io/api-status-codes"
image: "https://developer.agentsync.io/_og/d/c_Ocean.takumi,title_API+Status+Codes,description_~QnJhbmNoIG9uIHRoZSBIVFRQIHN0YXR1cyBjb2RlIOKAlCBhbmQgb24gY29kZSB3aGVyZSB2MiBwcm92aWRlcyBpdCDigJQgcmF0aGVyIHRoYW4gcGFyc2luZyBtZXNzYWdlIHRleHQuIEV4YWN0IGVycm9yIHNoYXBlcyB2YXJ5IGJ5IGVuZHBvaW50IGFuZCBzY2VuYXJpby4,props_eyJ0aGVtZSI6eyJtb2RlIjoibGlnaHQiLCJjb2xvcnMiOnsicHJpbWFyeSI6IiMxODdFRkYifX19,p_Ii9hcGktc3RhdHVzLWNvZGVzIg,s_7F0MtEuodBFVBSBS.png"
---

# API Status Codes

Branch on the HTTP status code — and on `code` where v2 provides it — rather than parsing message text. Exact error shapes vary by endpoint and scenario.

## [Success Responses](#success-responses)

| Code | Meaning                                                                          |
| :--- | :------------------------------------------------------------------------------- |
| 200  | The request succeeded and the body contains the requested data                   |
| 201  | The resource was created; the body contains it                                   |
| 202  | Accepted for processing, but not finished — results become available asynchronously |

## [Error Formats](#error-formats)

### [v2 — Contracting v2, Hierarchies & Identity](#v2-contracting-v2-hierarchies-identity)

```json
{
  "message": "Validation failed",
  "details": [
    { "param": "primaryEmail", "message": "must not be blank" }
  ],
  "code": "validation_failed"
}
```

| Field   | Description                                                                 |
| :------ | :-------------------------------------------------------------------------- |
| message | Human-readable summary. Do not parse it for branching.                      |
| details | Per-field validation errors (param + message). Empty for non-400 responses. |
| code    | Stable machine-readable code — branch on this.                              |

**Identity `code` values:** `validation_failed`, `unauthorized`, `unauthorized_scope`, `resource_not_found`, `conflict`, `unprocessable`, `unsupported_media_type`, `rate_limited`, `internal`.

> **Contracting v2 does not return `code`** — only `message` and `details`. Branch on the HTTP status code for those endpoints.

> **`404` instead of `403` across accounts:** requesting a v2 resource that exists but belongs to another customer returns `404`, never `403`, so resource existence is not leaked across account boundaries. A `403` means your token lacks the required scope.

### [ProducerSync](#producersync)

```json
{
  "timestamp": 1613510729601,
  "status": 500,
  "error": "Internal Server Error",
  "message": "Error message describing why this was an error.",
  "path": "/v2/{endpoint}"
}
```

## [Errors and What To Do](#errors-and-what-to-do)

| Code      | Meaning                                             | What to check                                                                    |
| :-------- | :-------------------------------------------------- | :------------------------------------------------------------------------------- |
| 400       | Validation error in parameters or body              | Parameter names, required fields, and value formats. v2 lists the offending fields in details |
| 401       | Missing or invalid credentials                      | The Authorization: Bearer header, whether the token has expired, and that client_id/client_secret match the token URL you called |
| 403       | Authenticated, but not permitted                    | Your token is missing a required scope — see Scopes                              |
| 404       | No matching resource                                | The endpoint path and any ID or NPN in it. On v2, also means the resource belongs to another account |
| 405       | Unsupported HTTP method for this endpoint           | Whether you're writing to a read-only surface — all Contracting v2 endpoints are GET |
| 429       | Rate limit exceeded                                 | Back off and retry — see Rate Limits                                             |
| 500       | Unexpected server-side error                        | Do not retry immediately. These are usually transient and alert our team automatically |
| 502 / 504 | Invalid or missing response from an upstream server | Usually transient; retry with backoff                                            |

> Requests that return a `404` for a non-existent NPN are not billed.

## [Reporting an Error](#reporting-an-error)

Include the trace ID from the response headers when you contact [support@agentsync.io](mailto:support@agentsync.io) — it lets us find your exact request in our logs. Capture it on failures, not just successes. See [Traceability](https://developer.agentsync.io/api-traceability) for the header name for each API.