Errors

The Local eSIM Partner API uses standard HTTP status codes to indicate success or failure.

Status codes

Code	Meaning
`200`	Customer already existed; tags were added successfully.
`201`	New customer created successfully.
`400`	Request body failed validation. See `message` for details.
`401`	Authentication failed. Your API key is missing, malformed, revoked, or otherwise invalid.
`405`	Method not allowed. Only `POST` is supported on this endpoint.
`422`	Shopify rejected the request data. See `message` for details.
`500`	An unexpected error occurred. Try again; if it persists, contact support with the `requestId`.
`502`	Communication with the upstream Shopify API failed. Try again.

All error responses are JSON with this structure:

{
  "error": "invalid_input",
  "message": "Invalid email address",
  "requestId": "8b3a1d2c-7e91-4f2b-9c0e-1b6f0e6f5a3d"
}

error — a machine-readable error code.
message — a human-readable explanation (not always present, e.g. on generic 401s).
requestId — a unique identifier for the request. Include this in any support communication.

`error`	When you'll see it
`invalid_input`	Request body validation failed (bad email format, empty tags, etc.).
`unauthorized`	Authentication failed.
`method_not_allowed`	You sent a method other than POST.
`shopify_rejected`	The request data passed our validation but Shopify rejected it.
`upstream_error`	Shopify returned an error or was unreachable.
`internal_error`	An unexpected error on our end.

Safe-to-retry status codes: 502, 500. The endpoint is idempotent on email — repeated calls with the same email won't create duplicates.

Do not retry on 400, 401, 405, 422 — these indicate a client-side problem that retrying won't fix.

If you're stuck on an error, email partners@local-esim.com with:

The requestId lets us trace your call through our system end-to-end.