Skip to main content

API Troubleshooting

This page is organized by symptom (what you are seeing) and walks you from the likely cause to the fix. For a code-by-code reference of HTTP status codes and retry guidance, see Error Handling.

Before You Begin​

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.
  • You are using the correct base URL and credentials. Match the base URL to your 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 you send requests, 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 your integration. Capture every response so you can correlate failures 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 same environment you are calling.
  • Extra whitespace in the credentials. A trailing space or line break copied into the client_id or client_secret will cause authentication to fail.
  • You are using a user login token, not 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.
  • You are using a user token 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 your network allows outbound HTTPS to *.api.ecourtdate.com on port 443. Agency firewalls often block this by default.
  • Confirm you are using the correct base URL for your 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:

  • You may be pointed at staging. Records created against staging.api.ecourtdate.com will not appear in a production region.
  • You may be calling the wrong region. Each region (US East, US West, US South, US Texas, Multi-Region) has its own base URL. Confirm you are reading from the same base URL you wrote to. 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 your 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"​

You need a Default Agency 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 your 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. Make sure you are reading subsequent pages rather than only the first. See Pagination.
  • Results are scoped to the agency. When your 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 you exceeded your client's rate limit. Wait at least 1 minute and retry with exponential backoff. Monitor the rate limit headers to throttle proactively. See Rate Limits.

Getting Help​

If you cannot resolve an issue, open a support ticket: sign in to the eCourtDate app (staging or production) under your Default Agency and click the tickets button in the bottom-right corner.

Include the following so support can trace the request:

  • The API client you are using (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)

You can find the request and response details 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​