Error Handling

When you send a request to the eCourtDate API, the server responds with an HTTP status code that indicates whether the request succeeded or what went wrong.

• 2xx (Success): Your request worked. 200 OK means everything went fine.
• 4xx (Client Error): Something is wrong with your request. These are issues you can fix on your end.
• 5xx (Server Error): Something went wrong on the eCourtDate side. These are typically temporary.

HTTP Status Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request body or missing required parameters
401	Unauthorized	Missing or invalid Bearer token
403	Forbidden	Agency inactive or insufficient permissions
404	Not Found	Resource or endpoint does not exist
405	Method Not Allowed	Wrong HTTP method for the endpoint
409	Conflict	Duplicate detected within the deduplication window
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server-side error
503	Service Unavailable	API temporarily unavailable
504	Gateway Timeout	Request timed out

Handling Each Response

400 Bad Request

The request body is invalid or a required parameter is missing.

Troubleshooting:

• Check that the request body is valid JSON
• Verify all required parameters are included (refer to the endpoint documentation)
• Check field types: strings, integers, booleans, and dates must match expected formats
• Timestamps must be in UTC with the format YYYY-MM-DD H:i:s
• Review the response body for specific field-level error messages
• Check Console > Logs for the full request and response

Best practice: Log the full response body when you receive a 400. The error message typically identifies the exact field or validation rule that failed.

401 Unauthorized

The Authorization header is missing, the Bearer token is invalid, or the token has expired.

Troubleshooting:

• Verify the Authorization header is set to Bearer {access_token}
• Confirm the access token has not expired; request a new token from the /oauth/token endpoint
• Confirm the API client has not been revoked in Console > APIs
• Verify you are using the correct environment (staging vs. production tokens are not interchangeable)

Best practice: Implement automatic token refresh. When you receive a 401, request a new access token and retry the original request. See API Authentication.

403 Forbidden

The request was authenticated but not authorized. Common causes:

• Agency is inactive: The agency associated with the API client must have an active status
• Permission denied: You are using a user token instead of an API client token. API endpoints require client credentials, not user session tokens.
• Insufficient permissions: The API client does not have the required permissions for this operation

Troubleshooting:

• Confirm the agency status is active
• Verify you are authenticating with an API client (client_id / client_secret), not a user token
• Check that the API client has the necessary permissions for the endpoint

Best practice: Set up monitoring for 403 responses. Repeated 403 errors may indicate a misconfigured integration or a revoked client.

404 Not Found

The endpoint or resource does not exist.

Troubleshooting:

• "Agency Not Found": You need a Default Agency configured. Set this in the Console.
• Endpoint not found: Verify the URL path, including the API version prefix (/v1/)
• Resource not found: Confirm the UUID or identifier in the URL is correct and belongs to the authenticated agency
• Check that you are using the correct environment base URL. See Environments.

Best practice: When looking up resources by UUID, handle 404 gracefully. The record may have been deleted or may belong to a different agency.

405 Method Not Allowed

The HTTP method (GET, POST, PATCH, DELETE) does not match what the endpoint expects.

Troubleshooting:

• Verify the correct HTTP method for the endpoint (e.g., POST for creating records, PATCH for updating, GET for reading)
• Check for typos in the URL that may be routing to a different endpoint

409 Conflict

A duplicate was detected. The deduplication check prevents the same message from being sent multiple times within a 30-minute window.

Troubleshooting:

• Use the skip_duplicate = true parameter on the /messages or /messages/oneoffs endpoint to bypass the duplicate check
• Set a scheduled_at value more than 30 minutes from the previous message
• Use the duplicate_buffer and duplicate_interval parameters to control the deduplication window (defaults to 30 minutes before and after scheduled_at)
• Wait 30+ minutes from the original scheduled_at before retrying
• Ensure message content is unique

See Idempotency and Deduplication for details on how deduplication works.

429 Too Many Requests

You have exceeded the rate limit for your API client.

Troubleshooting:

• Wait at least 1 minute before retrying
• Implement exponential backoff: wait 1 minute, then 2 minutes, then 4 minutes between retries
• If you are on a Dedicated plan, configure the Allowed IPs setting and contact support through the Help Center to request a rate limit increase

See Rate Limits for current limits and headers.

Best practice: Monitor the rate limit headers in API responses to proactively throttle requests before hitting the limit.

500 Internal Server Error

An unexpected error occurred on the eCourtDate side.

Troubleshooting:

• Check Console > Logs for the request and response details
• Verify the request body and parameters match the API documentation
• Retry the request after a short wait (1 minute)
• If the error persists, contact support through the Help Center with the request details

Best practice: Do not retry 500 errors aggressively. A single retry after 1 minute is reasonable. If it persists, the issue requires investigation.

503 Service Unavailable

The API is temporarily unavailable, usually during maintenance or high load.

Troubleshooting:

• Wait at least 1 minute and retry
• Check status.ecourtdate.com for platform status and maintenance announcements
• If the error persists, contact support through the Help Center

504 Gateway Timeout

The request timed out before completing, usually due to a temporary network issue.

Troubleshooting:

• Wait at least 1 minute and retry
• For write operations (POST, PATCH), check whether the resource was created before retrying to avoid duplicates
• If the error persists, contact support through the Help Center

Retry Strategy

API requests can fail for temporary reasons. Implement a retry strategy with exponential backoff:

1. First retry: Wait 1 minute
2. Second retry: Wait 2 minutes
3. Third retry: Wait 4 minutes
4. Maximum retries: Stop after 3 to 5 attempts and alert your operations team

Which codes to retry:

Code	Retry?	Notes
400	No	Fix the request; retrying the same payload will produce the same error
401	Yes	Refresh the access token first, then retry
403	No	Fix permissions or agency status
404	No	Fix the URL or resource identifier
409	Conditional	Only if you adjust the deduplication parameters
429	Yes	Wait for the rate limit window to reset
500	Yes	Retry once after 1 minute
503	Yes	Retry with backoff
504	Yes	Retry with backoff

Message Retry Behavior

eCourtDate automatically retries messages that fail due to temporary issues. You do not need to resend failed messages yourself.

Common reasons for automatic retries:

• Temporary network issues
• Temporary spam blocks
• Volume limits reached
• Carrier or gateway issues

Retry limits:

• Messages stop retrying 24 hours after the original send time
• Messages linked to an event stop retrying once the event date has passed
• Retries resume after carrier or gateway outages are resolved

Monitoring retries:

• Enable the Issues Emails setting in General Settings to receive notifications when messages are automatically retried
• View carrier campaign status in Billing > Campaigns
• Monitor delivery via Reports and Dashboards
• Enable Auto Run Lookups in Settings to validate contacts before sending. If a landline is detected, the message is automatically switched to a voice call.

Getting Help

If you cannot resolve an API error, contact support through the Help Center. Include the following:

• API endpoint and parameters
• Request body (redact any secrets or tokens)
• Response body and status code
• Timestamp of the failed request (UTC, format: YYYY-MM-DD H:i:s)

You can find all of this in Console > Logs. See Audit Logging for details.