Error Handling

The ErzyCall REST API uses standard HTTP status codes and returns errors in a consistent JSON envelope.

Error Envelope

All error responses follow this format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid query parameters",
    "details": [
      {
        "field": "phone",
        "message": "Must be E.164 format (e.g., +14155551234)"
      }
    ]
  }
}

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Error Codes Reference

Idempotency

For POST requests, you can include an Idempotency-Key header to safely retry requests without creating duplicate resources.

curl -X POST "https://app.erzycall.com/api/v1/calls" \
  -H "X-API-Key: ek_live_abc123" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{"to": "+14155551234", "from": "+14155559999"}'

• The first request creates the resource and caches the response.
• Subsequent requests with the same Idempotency-Key, method, and path return the cached response.
• If you reuse the key with a different request body, the API returns a 409 IDEMPOTENCY_MISMATCH error.

Best Practices

• Always check the error.code field for programmatic error handling, not the HTTP status alone.
• Handle 429 errors with backoff and retry logic. See Rate Limiting.
• Use idempotency keys for all POST requests to safely handle network retries.
• Log error responses including the full error envelope for debugging.