Errors

Handle Wingspan V3 errors consistently by checking the HTTP status and code, then retrying only the responses that support retries. Every V3 endpoint returns errors in the same format, so one error handler covers the whole API.

The error format

Errors come back with an HTTP status of 400 or higher and a body of type application/problem+json, following RFC 9457:

{
  "type": "https://api.wingspan.app/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request failed validation.",
  "code": "ValidationError",
  "requestId": "3f2c9a7e1b4d4e0f9a8c6b5d2e1f0a93",
  "errors": [
    { "field": "dueDate", "code": "Required" },
    { "field": "lineItems", "code": "TooShort" }
  ]
}

Branch on code, not detailCode

code comes from a fixed list (below) and keeps its meaning. Services can add detailCode values without notice, so your code can encounter values it does not recognize. Use detailCode for logging, dashboards, and support tickets. Make decisions on code and status. If you inspect detailCode, handle unknown values by falling back to code.

detailCode always has the form {service}.{Reason}. The service part tells you which area handled the request: payments, finance, onboarding, compliance, users (identity and Accounts), integrations (accounting connections), operations (async operations), or revenue (plans and subscriptions). Quote requests use the older prefixes currency and amount.

Nothing is dropped silently

If a request contains a field, query parameter, filter, or expand value that the operation doesn't accept, the request fails with 422 ValidationError and the problem is listed in errors[]. Wingspan doesn't ignore the bad part and return success. When a request succeeds, every field you sent was accepted.

HTTP status codes

A missing or wrong Content-Type returns 422 ValidationError. Send Content-Type: application/json on every request with a body.

Error codes

Field error codes

Each entry in errors[] has one of these codes:

Handling errors well

Which errors to retry

Start exponential backoff at about one second and double the delay after each attempt. Add random jitter, cap the delay at about 30 seconds, and stop after a limited number of attempts. Always honor Retry-After when it is present.

Retrying creates and money movement

Send an Idempotency-Key on every create and every money-moving request, and reuse the same key when you retry. Wingspan stores the response and replays it, so a retry doesn't create a second record or move money twice.

Responses with a 5xx status aren't stored, so a retry after a 5xx runs the request again. The first attempt may have finished before the error. Before you retry a create after a 5xx, look the record up by its externalId if you set one, or re-read the resource you were changing. See Idempotency.

429 compared with 503

A 429 means you sent more requests than your quota allows. Slow down and follow Retry-After. A 503 means Wingspan or one of its providers is temporarily unavailable, and it has nothing to do with your request volume. Back off and retry. Wingspan never returns 429 for its own outages, so a 429 always means you should reduce your request rate.

409 compared with 412

A 409 means the request conflicts with the resource's state: the resource is in the wrong status, or a record like it already exists. Resending the same request won't help until the state changes. A 412 means someone changed the resource after you read it. Your request may still be valid, but it was written against an old version. Re-read the resource, check that your change still makes sense, and retry with the new ETag.

Use requestId with support

Log requestId with every error, alongside the method, path, and status. When you contact support, include the requestId and the time of the request. It lets us find the exact request in our logs without you sending payloads that may contain personal or financial data.

Check every item in a bulk operation

A batch can finish while individual items fail. After a batch completes, list its items with filter[status][anyOf][]=Failed and read each item's statusReason. See Batches and bulk operations.

From V1

• V1 errors had a numeric code and a message. V3 errors have an HTTP status, a string code from the table above, and per-field errors[] on 422.
• V1 returned 400 for most validation failures. V3 uses 400 only for requests that can't be read, and 422 for invalid values.
• V1 returned 208 Already Reported for a duplicate bulk payable item. V3 returns the original response when you retry with the same Idempotency-Key, and 409 ResourceConflict for a duplicate externalId.
• V1 put bulk item errors in metadata.errorMessage. V3 puts them in each batch item's statusReason.

Related pages

• Idempotency
• Concurrency and ETags
• Rate limiting
• Async operations