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

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

v2 — Contracting v2, Hierarchies & Identity

{
  "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

{
  "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

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.

Include the trace ID from the response headers when you contact support@agentsync.io — it lets us find your exact request in our logs. Capture it on failures, not just successes. See Traceability for the header name for each API.