Skip to main content
Start with a minimal read-only request so product provisioning and side effects do not obscure transport or authentication failures:
Redact the Authorization header before sharing command output.

​
Diagnostic sequence

  1. Confirm the request uses https://api.telnyx.com/v2 and the method/path from the API reference.
  2. Confirm the header is exactly Authorization: Bearer <key>.
  3. Confirm that the environment variable exists in the current process, then confirm the key has not expired or been revoked and belongs to the expected account.
  4. Record the HTTP status, Telnyx error code, title, detail, and source fields.
  5. Compare the request with the endpoint schema, including media type, required fields, formats, and query parameters.
  6. Check account level, balance, resource ownership, and product provisioning when authorization fails.
  7. Apply rate-limit or retry handling only after classifying the failure.

​
Common failures

​
401 Unauthorized

Check for a missing Bearer header, truncated or invalid key, revoked key, or an environment variable that was not loaded by the current shell or process. Inspect only whether the variable is present—do not print its secret value. Create or rotate the key only after separating a local environment-loading failure from an API credential failure, then repeat the read-only balance request.

​
403 Forbidden

Authentication succeeded, but the operation is not permitted. Check resource ownership, account verification, product capability requirements, provisioning, and restrictions shown in Mission Control Portal. Do not repeatedly retry a 403 without changing the access condition.

​
404 Not Found

Confirm the API version, path, and resource identifier. A resource belonging to another account can also be unavailable to the current credential.

​
400 or 422 validation failure

Read every member of the errors array. Use source.pointer for a request-body field and source.parameter for a query parameter. Correct the request before retrying.

​
429 Too Many Requests

Stop requests in the affected scope and follow API rate limiting. Honor Retry-After when present.

​
5xx or network failure

Check Telnyx Status and preserve request context. Retry only when the operation is safe according to API retries and reliability. A timed-out mutating request can still have completed.

​
Correct common curl mistakes

​
Missing Bearer scheme

Incorrect:
Correct:

​
Query strings with square-bracket parameters

Quote URLs containing & so the shell does not split the command. Also disable curl URL globbing when parameter names contain square brackets. Incorrect:
Correct:
Percent-encoding the brackets as %5B and %5D is equivalent to using --globoff.

​
Collect support evidence

Provide the UTC timestamp, method and path, HTTP status and Telnyx error code, a returned request or correlation identifier when the response supplies one, redacted request and response bodies, product resource identifiers, and reproduction frequency. Never provide API keys, Bearer headers, webhook signing keys, or unredacted personal data.

​
References