Issue Summary:
When utilizing the TrustedForm Certificate API, users may encounter a range of issues—from improperly formatted certificate URLs, expired or non‐retainable certificates, authentication and HTTP method errors to lead matching mismatches. These errors can result from misconfigured API requests, incorrect payload formatting or outdated certificate data.
Impact:
Failures or errors in the Certificate API can prevent proper storage of proof of consent and mismatches between lead data and certificates. This affects publishers, lead buyers, automated integrations (via LeadConduit or custom solutions), and legal compliance teams, increasing the risk of non‑compliance, data discrepancies, and potential litigation.
Common Errors, Causes, and Fixes
| Symptom / Error | Root Cause | Description | Quick Fix |
|---|---|---|---|
| Certificate not retained or returns HTTP 404/410 | Expired certificate or invalid URL; certificate outside retention window | The certificate URL may be misformatted, expired (beyond 72 hours or 90 days with form submission), or non-existent. | Verify the certificate URL begins with “https://cert.trustedform.com/” and that it is within the valid retention period. |
| HTTP 403 Forbidden response | Incorrect or missing API key in HTTP Basic Authentication | The API key is either incorrect, missing, or the authentication header is misconfigured. | Confirm credentials and ensure the Authorization header is set with username “API” and the correct API key as password. |
| HTTP 400 or HTTP 406 errors | Malformed request payload or certificate ID formatting issues | When the JSON (or URL‑encoded) payload does not conform to the required schema or the certificate token is misformatted. | Revisit the API documentation, validate the JSON schema, and ensure that the certificate ID is correctly formatted. |
| HTTP 405 Method Not Allowed | Incorrect HTTP method (e.g. using GET instead of POST) or using sandbox cert | The Certificate API requires a POST request for retention; sandbox certificates cannot be retained. | Use an HTTP POST and, if testing with sandbox certificates, note that they cannot be retained. |
| Timeout or HTTP code 0 error | Network connectivity issues or client timeout settings too low | The API request timed out due to slow network responses or low timeout configuration. | Increase your client timeout setting and verify network connectivity; then retry the request. |
| Lead matching failure (Email and/or phone don’t match) | Mismatch between posted lead data and lead data recorded in the certificate | The provided email or phone do not match those captured in the certificate; or lead data was not detected. | Confirm that submitted contact information is correct and retry lead matching. |
| Payment Required (HTTP 402) | Account billing or subscription issue | An account payment or subscription issue may block certificate retention. | Check your account’s billing status and subscription level with TrustedForm; update payment information if needed. |
Step‑by‑Step Troubleshooting
Step 1 – Verify Your API Request Configuration
- Confirm that your endpoint URL is correctly set to start with:
“https://cert.trustedform.com/” - Ensure you are using an HTTP POST request.
- Verify the proper HTTP headers are set:
- Accept: application/json
- Content-Type: application/json (or application/x-www-form-urlencoded as required)
- api-version header (e.g., “4.0”) that matches your account settings.
- Confirm HTTP Basic Authentication is implemented properly with the username “API” and your valid API key as the password.
Expected Result:
The API request is properly formulated and authenticated; a valid certificate retention response (HTTP 201 Created) or a meaningful error message is returned.
Step 2 – Validate the Certificate URL and Payload
- Ensure the certificate URL begins with “https://cert.trustedform.com/” and does not include extraneous paths or fragments.
- Confirm that the lead was created within its valid retention window (72 hours by default, extended to 90 days if a form submission was detected).
- Check that the request payload includes all required fields, including lead matching parameters (email and/or phone), and conforms to the specified JSON schema.
Expected Result:
The certificate URL is valid and all parameters are correctly formatted, leading to a successful response.
Step 3 – Inspect the API Response Details
- Review the response’s HTTP status code and JSON body, focusing on the “outcome” and “reason” fields.
- If one operation fails (e.g. lead matching fails), the others (e.g. retain) will not be affected and may still succeed.
Expected Result:
If the outcome is “failure” or “error” then the “reason” field indicates the corrective measure needed.
Step 4 – Retry and Monitor
- After addressing any configuration or data issues, resend the API request.
- Monitor any logs the service used to make the API request provides.
- In cases of intermittent server errors (HTTP 500, 502, 503), wait a few minutes before retrying to see if the issue resolves.
Expected Result:
Monitoring confirms no further errors occur.
Error Codes & Their Meanings (If Applicable)
| Error Code | Meaning | Typical Fix |
|---|---|---|
| 0 | Client-side error (network issues or timeout reached) | Check your network connection and consider increasing the client timeout before retrying the request. |
| 201 | Success – Certificate successfully retained | No action is required; the certificate was retained correctly. |
| 400 / 406 | Bad Request – Malformed certificate ID or invalid payload | Correct the certificate URL format and ensure the payload strictly adheres to the API schema. |
| 402 | Payment Required | Verify your account’s billing status and subscription; update payment if necessary. |
| 403 | Forbidden – Authentication failure | Re‑authenticate by verifying and possibly regenerating your API key, ensuring the Authorization header is correctly formatted. |
| 404 | Not Found – Certificate is not found (expired or invalid URL) | Check that the certificate URL is correct and within its retention window; do not retry if it is expired. |
| 405 | Method Not Allowed | Use the proper HTTP POST method for certificate retention requests. |
| 410 | Gone – Certificate has expired and is pending deletion | Do not retry with this certificate; obtain a new, valid certificate URL. |
| 500, 502, 503 | Server errors – Internal issues or temporary gateway problems | Wait a few minutes then retry the API request; if persistent, contact TrustedForm support with error logs. |
8. FAQ
What does it mean when my API call returns HTTP 403?
It indicates an authentication failure. Verify that your HTTP Basic Authentication header includes “API” as the username and your current, valid API key as the password.
How can I tell if a TrustedForm certificate URL is valid?
The URL must start with “https://cert.trustedform.com/”. Additionally, you can use the TrustedForm Validity Check endpoint or the “format is valid” operator in LeadConduit to determine if the certificate is valid and not expired.
What are common causes of lead matching failures?
Lead matching failures occur when the submitted email or phone number do not match the data stored in the certificate.
Why might my request timeout or return HTTP code 0?
This typically indicates client-side issues such as network connectivity problems or overly strict timeout settings. Adjust your network settings or increase the timeout duration before retrying.
Can sandbox certificates be retained?
No. Sandbox mode certificates are generated for testing only and cannot be retained.
What should I do if I receive an HTTP 402 Payment Required error?
This error signals an account payment or subscription issue. Verify the billing status of your account and update or contact support if necessary.
Glossary
| Term | Definition |
|---|---|
| Certificate API | The TrustedForm API endpoint used for retaining, verifying, and retrieving TrustedForm certificates that document consumer consent. |
| Retain | The operation of storing a TrustedForm certificate in your account for long‐term access and legal protection, typically for a default period (e.g., 5 years). |
| Lead Matching | A process where the lead’s submitted contact details (e.g., email, phone) are normalized, hashed, and compared with data stored in the certificate. |
| API Key | A unique alphanumeric string used in HTTP Basic Authentication that authorizes API requests to TrustedForm. |
| Sandbox Certificate | A test certificate generated in a sandbox environment; these are for testing purposes and cannot be retained. |
| Retention Window | The time frame during which a TrustedForm certificate can be retained or queried; 72 hours by default and extended to 90 days if a form submission is detected. |
| Normalization | The process of standardizing data inputs (e.g., converting emails to lowercase, removing formatting from phone numbers) before hashing for matching. |
| Validity Check | An API or field validation process that confirms whether a TrustedForm certificate URL is valid, exists, and has not expired. |
| HTTP Basic Authentication | A method for transmitting credentials (username and password) in an HTTP header after encoding them in Base64, used to authorize API requests to TrustedForm. |
Comments
0 comments
Please sign in to leave a comment.