Getting Started

Error Handling

Error codes, troubleshooting, and idempotency

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

HTTP StatusCodeDescription
400VALIDATION_ERRORInvalid request body or parameters. Check the field property for the specific field.
401UNAUTHORIZEDMissing or invalid API key.
402QUOTA_EXCEEDEDMonthly token or request quota reached.
403FORBIDDENValid key, but not authorized for this resource.
403FEATURE_NOT_ENABLEDThis API feature is not enabled for your organization.
404NOT_FOUNDResource does not exist or you don’t have access.
409CONFLICTDuplicate resource or conflicting state.
409IDEMPOTENCY_KEY_REUSEDIdempotency key was used with a different request body.
429RATE_LIMITEDToo many requests. See Rate Limits.
500INTERNAL_ERRORServer error. Retry with backoff.

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

Idempotency keys are scoped per organization and per endpoint. The same key string can be used on different endpoints without collision.

Retry strategy

Error CodeRetry?Strategy
VALIDATION_ERRORNoFix the request
UNAUTHORIZEDNoCheck your API key
RATE_LIMITEDYesWait for Retry-After header value
QUOTA_EXCEEDEDNoContact your account manager
INTERNAL_ERRORYesExponential backoff (1s, 2s, 4s), max 3 retries
CONFLICTNoResource already exists or is in a conflicting state

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.