Error Handling

Most API errors use this response shape:

{
  "error": {
    "code": "invalid_request",
    "message": "from and to are required"
  }
}

Use error.code for programmatic handling and log the full response for troubleshooting. Common codes include unauthorized, invalid_json, invalid_request, not_found, insufficient_balance, rate_not_found, no_active_trunk, cps_limit_reached, concurrent_call_limit_reached, answer_url_error, and originate_failed.

Integration checklist

Set up the smallest possible working integration before adding business logic. Use one API key, one application, one answer_url, one webhook_url, and one DID or outbound test number. Save the successful request and response bodies because they become the baseline for later troubleshooting.

When you add features, change one part of the flow at a time. If a call fails, check authentication first, then the route, then the answer_url response, then webhook delivery. That order usually separates setup errors from call-control errors quickly.

Copy/Paste Examples

Real Request

curl -sS https://api.minivoice.eu/v1/calls \
  -H 'Authorization: Bearer $MINIVOICE_API_KEY'

Real Response

{
  "data": [],
  "count": 0
}

Real Webhook Example

{
  "event": "call.completed",
  "created_at": "2026-05-29T12:10:00Z",
  "call": {
    "id": "call_123",
    "customer_id": "cust_123",
    "application_id": "app_123",
    "status": "completed",
    "direction": "inbound",
    "from": "+15551230001",
    "to": "+15551230002"
  },
  "variables": {},
  "data": {}
}

Common Use Case

Prepare the base integration for a receptionist IVR, appointment confirmation line, or payment reminder workflow before sending real callers through it.

Common Failure Case

{
  "error": {
    "code": "unauthorized",
    "message": "unauthorized"
  }
}

Use the error code for branching and log the full response body while testing.