Errors · AiPSEO API

PublicErrorEnvelope

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "The requested resource was not found.",
    "request_id": "req_example",
    "details": null
  }
}

The effective X-Request-ID is also returned as a response header on every control-plane response.

Stable codes

Code	Typical meaning
`AUTHENTICATION_REQUIRED`	Missing `X-API-Key`.
`INVALID_API_KEY`	Key rejected.
`INSUFFICIENT_SCOPE`	Key lacks required `x-required-scopes`.
`VALIDATION_ERROR`	Malformed headers/body; bounded field details only.
`RESOURCE_NOT_FOUND`	Missing or cross-owner resource (no existence leak).
`RESOURCE_CONFLICT`	Conflicting resource state.
`EXTERNAL_REFERENCE_CONFLICT`	External reference already in use for owner.
`RESOURCE_VERSION_REQUIRED`	Missing `If-Match-Version` (HTTP 428).
`RESOURCE_VERSION_CONFLICT`	Stale version.
`BINDING_TARGET_INACTIVE`	Binding target agent inactive.
`IDEMPOTENCY_CONFLICT`	Same key, different fingerprint.
`IDEMPOTENCY_IN_PROGRESS`	Claim held; respect `Retry-After`.
`UNSUPPORTED_CAPABILITY`	Capability not available.
`INTERNAL_ERROR`	Sanitized failure.
`RATE_LIMITED`	Reserved; not emitted by current slice.

Recovery notes

Do not retry version conflicts with a freshly fetched version unless a reviewed workflow confirms the mutation is still desired.
For IDEMPOTENCY_IN_PROGRESS, wait for Retry-After before retrying the same key.
Exact idempotent replays return Idempotency-Replayed: true without re-executing mutation logic.