Skip to main content

API Troubleshooting

This page is organized by symptom and moves from the likely cause to the fix. For a code-by-code reference of HTTP status codes and retry guidance, see Error Handling.

Before Starting​

Most API problems trace back to one of three setup issues. Confirm these before troubleshooting anything else:

  • An API client is configured in the Console. Create or locate one under APIs and have its client_id and client_secret ready. See Authentication.
  • The base URL and credentials are correct. Match the base URL to the environment and region, and remember that staging and production credentials are not interchangeable. See Environments & Regions.
  • The API client has at least a Default Agency configured. Without one, requests fail with "Agency Not Found".

How to Debug an API Issue​

Before diving into a specific symptom, gather the facts:

  • Check the API client's "Last Active" timestamp first. Each API client in the Console under APIs has a Last Active property that updates whenever one of its requests is logged. Start here: if "Last Active" is not updating after requests are sent, the API is not receiving requests from that client at all, and there will be no logs to inspect. The problem is upstream of the API, so verify the base URL, credentials, and environment.
  • Check Console > Logs. Once "Last Active" confirms requests are arriving, the Console Logs section records the full request and response for every API call, including the status code and body. This is the fastest way to see what the API actually received and returned.
  • Log status codes and response bodies in the integration. Capture every response so failures can be correlated with the exact payload that caused them. See Best Practices.
  • Reproduce in staging. The staging environment (staging.api.ecourtdate.com) simulates outbound messages without delivering them, so it is the safest place to isolate a problem. See Environments & Regions.

Authentication and Authorization​

401 Unauthorized even though my token looks valid​

The token is present but the API rejected it. Common causes:

  • The token expired or was revoked. Access tokens are valid for 1 year. If yours is older than that, or the API client was revoked in Console > APIs, request a new token from /oauth/token and retry.
  • Staging and production tokens are not interchangeable. A token issued by staging.api.ecourtdate.com will not work against a production region, and vice versa. Confirm the token came from the environment being called.
  • Extra whitespace in the credentials. A trailing space or line break copied into the client_id or client_secret will cause authentication to fail.
  • A user login token is in use instead of an API client token. API endpoints require a token from the OAuth2 Client Credentials flow, not a Console user session.

Verify a token quickly by calling:

curl -X GET https://staging.api.ecourtdate.com/v1/settings \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

A 200 OK confirms the token is active and shows which agency it is scoped to. See Authentication.

403 Forbidden​

The request authenticated but was not authorized:

  • The agency is inactive. The agency tied to the API client must have an active status.
  • A user token is in use instead of an API client token. API endpoints require client credentials, not a user session token.
  • The API client lacks the required permissions for the endpoint.

See Error Handling: 403 Forbidden for the full breakdown.

Connectivity​

Connection refused or request times out​

The request never reaches the API:

  • Make sure the network allows outbound HTTPS to *.api.ecourtdate.com on port 443. Agency firewalls often block this by default.
  • Confirm in use the correct base URL for the environment and region. A typo in the host will fail to connect. See the base URL table in the API Guide.

Wrong Environment or Region​

I created records but can't find them​

Records are scoped to the environment and region where they were created:

  • The request may be pointed at staging. Records created against staging.api.ecourtdate.com will not appear in a production region.
  • The request may be calling the wrong region. Each region (US East, US West, US South, US Texas, Multi-Region) has its own base URL. Confirm that reads and writes use the same base URL. See Environments & Regions.

My message was created but never delivered​

  • Staging does not deliver messages. It creates and tracks the message but does not send it. This is expected. Switch to the production region base URL to send real messages.
  • A send delay or schedule is in effect. Sending immediately with send_now: true requires the agency to have Default Message Delay set to 0 and Send Immediately enabled in settings. Otherwise the message follows the configured delay or its scheduled_at time. See Best Practices.

Not Found Problems​

"Agency Not Found"​

A Default Agency must be configured. Set this in the Console.

404 on an endpoint that should exist​

  • Verify the URL path includes the API version prefix (/v1/).
  • Check for typos in the path that may route to a different endpoint.

A resource returns 404 but I know it exists​

  • Confirm the uuid or reference in the URL is correct and belongs to the authenticated agency.
  • If the API client has access to multiple agencies, specify which one with the agency_reference query parameter, otherwise the resource may not be visible under the default agency:
GET /v1/clients?agency_reference=demo

See Authentication: Multi-Agency Access.

Unexpected or Empty Results​

A list endpoint returns fewer records than expected​

  • Results are paginated. Read subsequent pages rather than only the first. See Pagination.
  • Results are scoped to the agency. When the client spans multiple agencies, add agency_reference to target the correct one.

Unexpected 409 Conflict / Duplicates​

A 409 Conflict means the deduplication check caught a message that matches a recent one within a 30-minute window. To resolve:

  • Pass skip_duplicate: true on the /messages or /messages/oneoffs endpoint to bypass the check.
  • Set scheduled_at more than 30 minutes from the previous message.
  • Adjust the window with duplicate_buffer and duplicate_interval.

See Idempotency and Deduplication.

Data Format Issues​

A 400 Bad Request often comes down to formatting:

  • Timestamps must be UTC in the format YYYY-MM-DD H:i:s.
  • The request body must be valid JSON, with the Content-Type: application/json header set.
  • Field types must match. Strings, integers, booleans, and dates must be in the expected format. The response body usually names the field that failed validation.

See Error Handling: 400 Bad Request.

Rate Limiting (429)​

A 429 Too Many Requests means the client's rate limit was exceeded. Wait at least 1 minute and retry with exponential backoff. Monitor the rate limit headers to throttle proactively. See Rate Limits.

Getting Help​

To request help, create a support ticket in the Console: sign in, click the Help button in the bottom-right corner, and complete the Create a Ticket form (Region, Agency, Feature, and a Description). The current page is attached automatically, and updates appear under My Tickets in the same panel.

In the description, include:

  • The API client in use (its name from Console > APIs, never the client secret)
  • The API endpoint and parameters
  • The request body, with any secrets or tokens redacted
  • The response body and status code
  • The approximate time of the failed request (an exact UTC timestamp is not required)

Request and response details are in Console > Logs. Check status.ecourtdate.com for platform incidents and scheduled maintenance.

danger

Never share API client secrets or access tokens in support tickets or logs.

See Also​