Error Handling
When you send a request to any web API, the server responds with a numbered HTTP status code that tells you whether the request succeeded or what went wrong — similar to getting a receipt confirming your order versus an error message explaining a problem.
The codes are grouped into categories:
- 2xx (Success) — Your request worked. For example,
200 OKmeans everything went fine. - 4xx (Client Error) — Something is wrong with your request. You may have sent invalid data, used an expired token, or requested something that doesn't exist. These are issues you can fix on your end.
- 5xx (Server Error) — Something went wrong on the eCourtDate side. These are typically temporary. Retry after a short wait, and contact support if they persist.
HTTP Status Codes
| Code | Meaning | Action |
|---|---|---|
| 400 | Bad Request | Validate request body and required parameters. |
| 401 | Unauthorized | Check Bearer token; verify the API client has not been revoked. |
| 403 | Forbidden | Agency is inactive, or a user token is being used instead of an API client token. |
| 404 | Not Found | Check the endpoint path; configure a Default Agency if you receive "Agency Not Found." |
| 405 | Method Not Allowed | Confirm the correct HTTP method (GET, POST, PATCH, DELETE). |
| 409 | Conflict | Duplicate detected -- see Idempotency & Deduplication. |
| 429 | Too Many Requests | Rate limit exceeded -- see Rate Limits. |
| 500 | Internal Server Error | Contact support. |
| 503 | Service Unavailable | Retry after 1 minute. |
| 504 | Gateway Timeout | Retry after 1 minute. |
Carrier Error Codes and Reasons
Carrier-level error codes and error reasons are available as JSON files for programmatic consumption:
- Error codes: https://assets.ecourtdate.com/app/js/error_codes.json
- Error reasons: https://assets.ecourtdate.com/app/js/error_reasons.json
See the Error Catalog for the complete reference of all error codes and their resolutions.
Message Retry Behavior
eCourtDate automatically retries messages that fail due to temporary issues, including:
- Temporary network issues
- Spam blocks
- Volume limits
- Carrier or gateway issues
Messages stop retrying 24 hours after the original send time. Messages linked to an event stop retrying once the event date has passed.