Error Handling

All API errors follow a consistent envelope with machine-readable error codes.

Error response format

1
{
2
  "success": false,
3
  "error": {
4
    "code": "VALIDATION_ERROR",
5
    "message": "project_id is required",
6
    "field": "project_id"
7
  },
8
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
9
}

Always log the request_id (also in the X-Request-Id header) — it’s required for support lookups.

Error codes

Idempotency

All POST endpoints accept an Idempotency-Key header for safe retries:

$
curl -X POST https://api.pyramid-ai.com/api/v2/projects \
>
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
>
  -H "Content-Type: application/json" \
>
  -H "Idempotency-Key: my-unique-key-12345" \
>
  -d '{"name": "My Project"}'

How it works:

1. First request with a given key executes normally and caches the response
2. Subsequent requests with the same key and same body return the cached response (no duplicate side effects)
3. Same key with a different body returns 409 IDEMPOTENCY_KEY_REUSED
4. Keys expire after 24 hours

Retry strategy

Request IDs

Every response includes a unique request_id in both the response body and the X-Request-Id header. When contacting support, always include this ID for fast diagnosis.