Errors
The error envelope and every error code the API returns.
Every non-2xx response uses one envelope:
{
"error": {
"code": "GP_VALIDATION",
"message": "human sentence",
"requestId": "req_…",
"details": {},
"gpErrors": [{ "number": 4628, "text": "…", "node": "taUpdateCreateCustomerRcd" }]
}
}code— a stable machine code (the table below). Branch on this, not the message.message— a human-readable sentence; may change, never parse it.requestId— theX-Request-Idof the call; include it in support requests.details— code-specific extra data (e.g.issues[]for validation,reasonfor a plan limit).gpErrors— present onGP_VALIDATION: the raw eConnect error number(s) + our remediation hint.
Codes
| HTTP | code | when |
|---|---|---|
| 400 | VALIDATION_ERROR | zod failure or missing headers; details.issues[] |
| 401 | UNAUTHORIZED | bad, missing, or revoked key |
| 402 | PLAN_LIMIT | live-connection plan limit reached; details has reason, plan, current, limit |
| 403 | FORBIDDEN | key lacks the required scope, or the connection isn't in your org |
| 403 | WRITE_NOT_ENABLED | the object isn't on the connection's write whitelist |
| 403 | SANDBOX_READ_ONLY | a write was attempted on a sandbox connection |
| 404 | NOT_FOUND | unknown route or object id |
| 409 | IDEMPOTENCY_CONFLICT | same Idempotency-Key, different request body |
| 422 | GP_VALIDATION | eConnect rejected the document; gpErrors[] populated |
| 422 | ECONNECT_MISSING | the connection's GP install lacks the eConnect runtime; details.docsUrl |
| 429 | RATE_LIMITED | rate-limit bucket empty; retry after Retry-After |
| 502 | AGENT_ERROR | the agent returned a malformed or unexpected result |
| 503 | CONNECTION_OFFLINE | no live agent socket for the connection |
| 503 | AGENT_BUSY | the agent's request queue is full |
| 504 | AGENT_TIMEOUT | the tunnel round-trip exceeded its budget |
| 413 | PAYLOAD_TOO_LARGE | the result exceeded the frame cap; narrow the query |
| 500 | INTERNAL | anything else — logged; internals are never leaked |
For write-specific validation failures (422 GP_VALIDATION), see the eConnect error numbers and
hints in Writes & batches.