Errors

Common status codes

Validation errors (400)

Request bodies and query parameters are validated before your request reaches backend provisioning logic.

Examples that return 400:

• Invalid UUID format for customerID
• Invalid email or enum values
• PATCH .../contract with both term and plan — Cannot update both term and plan at the same time
• PATCH .../contract with neither term nor plan — No contract updates provided
• POST /customers without adminUser.email on non–hardware-only plans

Validation responses follow NestJS / Zod validation format (typically an array of messages in the response body).

Upstream errors

When the API calls internal PhoneLine+ or billing services, failures are mapped where possible:

• HTTP status from the upstream service is often passed through.
• Message body may include a message field from the upstream response.

Always log the HTTP status, response body, and your correlation ID for support requests.

Authentication errors

Refresh the JWT via POST /auth before retrying.

Client retry guidance

For async operations, prefer polling GET /jobs/{jobID} rather than repeating POST /customers without idempotency.

Support

Include in tickets:

• Timestamp (UTC)
• Request ID / correlation ID from your logs
• HTTP method and path (no secrets)
• Response status and body (redact tokens)