Error Codes

The Sporeline API error format, every status code it returns, and which errors are safe to retry.

developer

Error Codes

When a request fails, the Sporeline API returns an HTTP error status and a JSON body in a standard shape. This page covers that shape, the status codes, and how to handle each one.

The Error Envelope

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "weight_g must be >= 0.01",
    "retry": false,
    "request_id": "2f1c7d6e-4b0a-4f8e-9d1a-3c5b7e9f0a12",
    "field_errors": [
      {
        "field": "weight_g",
        "issue": "below_minimum",
        "expected": ">= 0.01",
        "received": "0"
      }
    ]
  }
}
FieldPresentMeaning
codeAlwaysA machine-readable error code. See the tables below
messageAlwaysA human-readable explanation
retryAlwaystrue if the same request may succeed later. false if you need to change the request first
request_idMost errorsThe ID of this request. Include it when you contact support
field_errorsSome 400 errorsOne entry per invalid field, with the field, the issue, and where available what was expected and received
required_plan402 onlyThe plan that allows the action

Every response also carries the request ID in the x-amzn-RequestId header, including errors whose body has no request_id.

Successful responses wrap their result in a data object instead: { "data": ... }.

Status Codes

StatuscoderetryWhen it happens
400BAD_REQUESTfalseThe request is invalid: a missing or malformed field, a value out of range, a bad next_token, an action the record’s current state doesn’t allow, or a method the endpoint doesn’t support
401SESSION_EXPIREDfalseThe credentials are missing or weren’t accepted. See Authentication
402UPGRADE_REQUIREDfalseThe action would go over a limit of your plan, such as the number of active blocks
403FORBIDDENfalseYour role isn’t allowed to do this. API keys run with the Manager role
404NOT_FOUNDfalseThe record doesn’t exist in your account, or the path or method doesn’t exist
409CONFLICTUsually falseThe request conflicts with the record’s current state, for example editing a delivery that’s already been delivered. When retry is true, the conflict should clear on its own
429n/an/aToo many requests. Retry with backoff. This comes from the gateway, so don’t rely on the body. See Rate Limits
500INTERNAL_ERRORtrueSomething went wrong on our side. The message is always generic
501NOT_IMPLEMENTEDfalseThe endpoint exists but this operation isn’t available yet
502SERVICE_UNAVAILABLEtrueA service Sporeline depends on failed. Try again shortly
503SERVICE_UNAVAILABLEfalseThe feature is switched off for now
Other 5xxSERVICE_UNAVAILABLEtrueThe request timed out or a backend was unavailable

Other Codes

Team and invitation endpoints use more specific codes:

codeStatusMeaning
ROLE_NOT_ALLOWED403You can’t assign, change or remove that role
SELF_ROLE_CHANGE403You can’t change your own role
SEAT_LIMIT_EXCEEDED409Your plan has no free seats
EMAIL_ALREADY_MEMBER409That email already belongs to a team member
INVITE_ALREADY_PENDING409That email already has a pending invitation

Errors from the Gateway

Some errors are returned before a request reaches Sporeline:

  • 401 for missing or rejected credentials
  • 403 when the firewall blocks an address that’s over the per-address limit
  • 404 for a path or method that doesn’t exist
  • 429 when the API throttle is exceeded
  • Other 5xx errors when a request times out

These responses have no request_id in the body. For 429 and firewall 403 responses, don’t rely on the body at all. Check the HTTP status code.

Handling Errors

  1. Branch on the HTTP status code first, then on code for detail.
  2. If retry is true, retry with exponential backoff, for example after 1, 2, 4 and 8 seconds.
  3. If retry is false, fix the request before sending it again. For 400 errors, field_errors says which fields to fix.
  4. Be careful retrying a create. If a POST times out, the record may have been created anyway. Check before sending it again, or you may end up with a duplicate.
  5. Log the request ID. If you need help, email support@sporeline.com with the request ID and the time of the request.

Related Pages