Error Handling

Every response from the 9Squid API follows the same envelope, whether it succeeds or fails. This page explains what each error looks like and how to handle it correctly.

Error Response Format

{
  "success": false,
  "message": "Descriptive error message",
  "statusCode": 400
}

The message field is human-readable and safe to surface in logs. Never rely on its exact wording in code — use statusCode for branching logic.

HTTP Status Codes

Code	Name	When it happens
`400`	Bad Request	Missing or invalid fields in the request body
`401`	Unauthorized	Missing, expired, or malformed Bearer token
`403`	Forbidden	Your token is valid but your role cannot access this endpoint
`404`	Not Found	The resource (deal, loan, subscription) does not exist
`409`	Conflict	A duplicate resource already exists (e.g. a `DRAFT` deal for this loan type)
`413`	Payload Too Large	Uploaded file exceeds the size limit
`422`	Unprocessable Entity	Request is well-formed but semantically invalid
`429`	Too Many Requests	Rate limit exceeded — see below
`500`	Internal Server Error	Unexpected platform error — contact support

Common Errors and Fixes

401 Unauthorized

{ "success": false, "message": "Unauthorized", "statusCode": 401 }

Cause: The Authorization header is missing, the token has expired, or it is malformed. Fix: Ensure every request includes Authorization: Bearer <your_token>. Contact support@9squid.com if your token has expired.

403 Forbidden

{ "success": false, "message": "Forbidden", "statusCode": 403 }

Cause: Your token is valid but your role (Originator or Investor) does not have access to this endpoint. Fix: Check the Role-Based Access table. If you believe you should have access, contact support.

409 Conflict — Draft Deal Already Exists

{
  "success": false,
  "message": "A DRAFT deal already exists for this loan type",
  "statusCode": 409
}

Fix: Call PATCH /originator/loans/:dealId to regenerate the upload URL for the existing draft, or DELETE it and start fresh.

413 Payload Too Large

Fix: Ensure your loan tape file is under the platform’s size limit. For large datasets use the Bulk Loan Upload workflow which handles chunked multi-deal submission.

429 Too Many Requests

{ "success": false, "message": "Too many requests", "statusCode": 429 }

The 9Squid API enforces a rate limit of 100 requests per 60 seconds per token. Exceeding this returns a 429 with a Retry-After header indicating how many seconds to wait.

Retry-After: 30
x-ratelimit-limit: 100
x-ratelimit-remaining: 0
x-ratelimit-reset: 56

Header	Description
`x-ratelimit-limit`	Total requests allowed per 60-second window
`x-ratelimit-remaining`	Requests remaining in the current window
`x-ratelimit-reset`	Seconds until the current window resets
`Retry-After`	Seconds to wait before retrying

Fix: Back off for the duration specified in Retry-After before retrying. See the retry strategy below.

Retry Strategy

Not all errors are worth retrying. Follow this decision tree:

Status	Retry?	Strategy
`400`	No	Fix the request — retrying will keep failing
`401`	No	Refresh your token first
`403`	No	Role issue — retrying won’t help
`404`	No	Resource doesn’t exist
`409`	No	Handle the conflict explicitly
`429`	Yes	Wait for `Retry-After`, then retry
`500`	Yes	Exponential backoff, max 3 attempts
Network timeout	Yes	Exponential backoff

Exponential Backoff Example

async function requestWithRetry(fn, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      const retryable = [429, 500, 502, 503, 504].includes(err.statusCode);
      if (!retryable || attempt === maxAttempts) throw err;

      const delay = Math.min(1000 * 2 ** attempt, 30000); // cap at 30s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Validating Before You Send

Most 400 errors can be avoided by validating locally first:

Loan type must be one of: Auto, Personal, Mortgage, Student, Business, Credit Card
File format must be text/csv or application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
Required fields are documented per endpoint in the API Reference
deal_id and file_name in the complete step must exactly match what was returned in the initiate step

Support

Before reporting an error, check status.9squid.com to see if it corresponds to an ongoing incident. If you encounter a 500 error or an undocumented error message, contact support@9squid.com with:

The full request (endpoint, headers, body — redact your token)
The full response body
A timestamp of when the error occurred

​Error Response Format

​HTTP Status Codes

​Common Errors and Fixes

​401 Unauthorized

​403 Forbidden

​409 Conflict — Draft Deal Already Exists

​413 Payload Too Large

​429 Too Many Requests

​Retry Strategy

​Exponential Backoff Example

​Validating Before You Send

​Support