Build with the record
Errors and integration practices
Handle unavailable data, network selection, response shapes, and retry behavior.
Check the response
Inspect HTTP status and Content-Type before reading the body as JSON. A 200 response from an unrelated host or route can be an HTML page. Use the hosts and paths shown in this reference.
API v1 errors
API v1 errors use application/problem+json with a stable code, a requestId and, for some errors, the param that failed. Codes: invalid_request and invalid_entity_id (400), authentication_required and invalid_credential (401), livemode_mismatch (403, a test-network record read without a test key), not_found, entity_not_found and agent_not_found (404), ambiguous_entity_id (409), rate_limited (429) and gateway_unavailable (503). detail is a readable message; branch on code, not on detail. Quote the requestId when you contact us.
Separate missing from unavailable
A 404 on a record read means the route did not find the requested record or file. A 5xx means the lookup failed. Keep those states distinct and never treat an outage as a successful verification.
Retry carefully
Use a request deadline and a small, bounded number of retries for transient read failures. Back off between attempts. API v1 allows 30 requests per minute and 1,000 per day without a key, and 600 per minute and 100,000 per day with one. A 429 response includes Retry-After in seconds; wait that long before retrying.
Preserve context
Store the identifier, selected network, source URL, and time of your read with any decision. Preserve the full registration URI, including its query. Avoid silently substituting a test-network record for a production record.
Respect data boundaries
Public reads should not require a private key, a browser session export, or a CMS administration key. Keep app sessions in the app. Confirm service authentication with the team before building protected workflows.
Get help
Contact Entity.ID with the route, response status, approximate UTC time, and a public record identifier. Omit secrets and identity documents. Describe the fields and availability your integration requires.