Standard Response Format

All Fuuffy API responses follow a consistent, predictable structure to ensure easy integration and error handling.

---

Response Envelope Pattern

Fuuffy API uses the envelope pattern. All responses are wrapped in a standard structure:

• Success responses — Data wrapped in a data object.
• Error responses — Errors wrapped in an error object.

This design provides Consistent parsing logic across all endpoints. Clear distinction between success and error. Extensible structure for future metadata. Aligns with common API best practices.

---

Success Response Format

data

json-string

Response payload. Structure depends on the endpoint (single object, array, or array with pagination).

Example - Single object

{
  "data": {
    "id": "shp_1234567890",
    "status": "pending",
    "tracking_number": "FUF123456789",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Example - Array or list

{
  "data": [
    {
      "id": "shp_1234567890",
      "status": "pending"
    },
    {
      "id": "shp_0987654321",
      "status": "delivered"
    }
  ]
}

Example - With pagination

{
  "data": [
    // ... array of items
  ],
  "pagination": {
    "total": 140,
    "page": 1,
    "per_page": 20,
    "total_pages": 8
  }
}

---

Error Response Format

error.code

string

Error code (e.g. numeric or machine-readable).

error.code_reason

string

Developer-readable error identifier.

error.message

string

Human-readable error message.

error.error_trace

json-string | array

Optional. Field-level validation or extra context.

Example - Validation error

{
  "error": {
    "code": "400000",
    "code_reason": "validation_error",
    "message": "Invalid request parameters",
    "error_trace": {"weight": "Missing required field 'weight'"}
  }
}

Example - OAuth error

{
  "error": {
    "code": "401021",
    "code_reason": "invalid_client_id_or_client_secret",
    "message": "Invalid client_id, client_secret, or session_key"
  }
}

---

HTTP Status Codes

Fuuffy API uses standard HTTP status codes.

Success codes (2xx)

Status	Meaning	Usage
200 OK	Success	Standard successful response
201 Created	Created	Resource successfully created
204 No Content	Success, no data	Successful deletion or update with no response body

Client error codes (4xx)

Status	Meaning	Common error codes
400 Bad Request	Invalid request	validation_error, invalid_request
401 Unauthorized	Authentication failed	unauthorized, invalid_token
403 Forbidden	Permission denied	forbidden, insufficient_permissions
404 Not Found	Resource not found	not_found, resource_not_found
422 Unprocessable Entity	Validation failed	validation_error, invalid_data
429 Too Many Requests	Rate limit exceeded	rate_limit_exceeded

Server error codes (5xx)

Status	Meaning	Common error codes
500 Internal Server Error	Server error	internal_error, server_error
503 Service Unavailable	Service down	service_unavailable, maintenance

---

Common Error Codes

Error code	HTTP status	Description
validation_error	400, 422	Request validation failed
invalid_request	400	Malformed request
general_exception	400	General exception
unauthorized	401	Authentication required or failed
invalid_token	401	Access token is invalid or expired
forbidden	403	Insufficient permissions
not_found	404	Resource does not exist
rate_limit_exceeded	429	Too many requests
internal_error	500	Server-side error

---

Best Practices for Integration

1. Always check HTTP status first

• Use the response status code to decide whether to parse data or error.
• Treat 2xx as success and parse data.
• For non-2xx, parse error and handle accordingly.

2. Parse the response envelope

• Check for presence of data or error in the JSON body.
• Do not assume a 200 response always has data; use the envelope to drive your logic.

3. Handle errors gracefully

• Map error.code or code_reason to user-facing messages or retry logic.
• For unauthorized or invalid_token, refresh the token and retry.
• For validation_error, surface error_trace when present.
• For rate_limit_exceeded, implement backoff and retry.

---

Why This Format?

Industry standards

This response format follows patterns used by:

• JSON:API specification
• Google Cloud APIs
• Stripe API
• GitHub API

Benefits

• Predictable — Same structure across all endpoints.
• Type-safe — Easy to type in TypeScript and other languages.
• Extensible — Metadata can be added without breaking changes.
• Clear — Obvious distinction between success and error.
• Standard — Familiar to developers from other APIs.

---

See Also

• Token Management — Caching and validating access tokens
• OAuth Authentication — Obtaining tokens
• API Overview — Base URLs and versioning