Errors

Every Public v1 failure uses the same top-level shape. Parse the error object for client behavior and retain meta.requestId when asking for support.

{
  "error": {
    "code": "invalid_request",
    "message": "The request is invalid.",
    "retryable": false,
    "details": [
      {
        "field": "query.username",
        "code": "invalid_format",
        "message": "Use a valid Profile username."
      }
    ]
  },
  "meta": {
    "requestId": "request-example"
  }
}

• code is a stable machine-readable value. Branch on it rather than matching message text.
• message is a human-readable summary and can change without changing the meaning of the response.
• retryable tells the client whether repeating the request may succeed.
• details identifies individual validation problems when available.
• meta.requestId correlates the failure with EnvoAPI diagnostics. It is also returned in the X-Request-Id header.

HTTP status codes

An operation’s generated reference is authoritative for the statuses it can return. Authenticated lookup operations use these common meanings:

Status	Meaning	What to do
400	Invalid request shape or value	Correct the parameters; do not retry unchanged.
401	Invalid or inactive API Key	Correct or rotate the credential.
402	Insufficient Available Credits	Add Credits or wait for a grant before retrying.
403	The Account is suspended or lacks access	Resolve the Account or access state.
404	The requested public resource was not found	Correct the selector or treat it as absent.
405	A known lookup route used a method other than GET	Use the method in the operation reference.
406	The requested representation is not acceptable	Request JSON using a supported Accept value.
415	The declared media type is unsupported	Remove the body or use the documented media type.
429	The Account’s rolling lookup limit was exceeded	Honor Retry-After; see Rate limits.
500	Internal failure or bounded response serialization failure	Retry only when error.retryable is true.
502	An upstream dependency returned an unusable response	Retry with bounded backoff.
503	Lookup is temporarily unavailable	Follow error.retryable and Retry-After when present.
504	The lookup deadline was exhausted	Retry with bounded backoff.

Handle failures safely

Check the HTTP status before interpreting a success body. For a failed request, branch on error.code and error.retryable; do not classify a failure by its message alone. Bound both the number of retries and total elapsed time, and honor Retry-After whenever it is present.

Do not retry validation, authentication, authorization, credit, or not-found failures unchanged. A retry is another Lookup Request: it consumes an account-wide rate-limit slot and can incur a Lookup Cost if admitted.

Record the request ID, operation, status, and stable code. Redact API Keys, Lookup Inputs, raw profile data, and sensitive query parameters from logs and error reports. See Authentication for credential safety.