Public API errors and troubleshooting – Firstbase

Introduction

The Firstbase Public API returns standard HTTP status codes and a consistent JSON error body. This article covers the error format, common status codes, and example scenarios. Endpoint-specific errors are documented on developers.firstbase.com for each operation.

Error response format

Most error responses use this structure:

{
  "errors": [
    {
      "detail": "Human-readable description of the error",
      "source": "request"
    }
  ]
}

detail: Description of what went wrong
source: Field or entity that caused the error (for example person:email, order, or request)

SCIM endpoints may return additional SCIM-formatted error bodies. Check the response body and status code together when debugging.

Common HTTP status codes

Code	Meaning	Typical causes
400	Bad request	Invalid input, unsupported country, missing required SCIM attribute, validation failure
401	Unauthorized	Missing or invalid API key
403	Forbidden	Feature not enabled for your organization or contract tier
404	Not found	Resource does not exist or is not visible to your organization (person, package, order, etc.)
409	Conflict	Business rule violation (duplicate email, invalid state transition, subscription field change, inventory order already processing)
429	Too many requests	Request rate exceeded. Back off and retry with exponential delay.
500	Server error	Unexpected failure. Retry may succeed; contact support if it persists.

Rate limits and retries

Protect your integration against transient failures and rate limiting:

Implement exponential backoff when you receive 429 or 500 responses.
Avoid tight polling loops on list endpoints. Use filters such as updatedAtFrom and updatedAtTo on GET /api/v1/inventory to fetch only recent changes.
Cache stable reference data (packages, regions, categories) instead of requesting it on every workflow step.

If you consistently hit rate limits, contact your Customer Success Manager to review integration patterns.

Example error scenarios

Scenario	Code	Example message
Invalid package ID	404	Package does not exist with ID: {packageId}
Invalid or unsupported country	400	{Country} is not supported. Supported countries are: {countries}
Person email already exists	400	Could not create user: {reason}
Missing primary phone number	400	Required attribute 'urn:ietf:params:scim:schemas:core:2.0:User:phoneNumbers.primary' is missing or blank
Invalid start date format	400	Attribute 'urn:ietf:params:scim:schemas:extension:firstbase:1.0:User.startDate' does not contain a valid date
Inventory order already processing	409	Only the PO number can be updated after processing begins
Duplicate userName on update	409	Conflict with an existing person record

These examples are not exhaustive. Always inspect the detail and source fields in the response body.

Next steps

developers.firstbase.com — per-endpoint error responses in the API reference
Firstbase API: What's available and how to use it — workflow FAQs (offboarding, giftable items, ITAD)