Error codes
Every error code the Org API can return.
Every error response from the Org API includes one of these codes, along with a matching HTTP status. See Errors for the response shape and how to handle them.
| Code | HTTP status | Meaning |
|---|---|---|
| MISSING_API_KEY | 401 | The request has no API key. Send it as Authorization: Bearer <key> or in the x-api-key header. |
| INVALID_API_KEY | 401 | The API key isn't recognized. Check that the whole key was copied, or create a new key. |
| REVOKED_API_KEY | 401 | The API key was revoked. After a key is rotated, the old key stops working when its grace period ends. Use the current key. |
| EXPIRED_API_KEY | 401 | The API key is past its expiration date. Create a new key. |
| IP_NOT_ALLOWED | 403 | The request came from an IP address this API key doesn't accept. Contact solarOS support to change the key's allowed addresses. |
| BILLING_ACCESS_DENIED | 402 | Your organization's solarOS subscription doesn't allow this request right now. The error message gives the reason. An Owner can review the subscription in solarOS. |
| INSUFFICIENT_SCOPE | 403 | The API key doesn't have a scope this operation needs. The error message names the scope. Use a key that has it. |
| FORBIDDEN | 403 | The API key can't change this record. For example, only the key that created an activity can edit it. |
| RATE_LIMITED | 429 | Too many requests. Wait the number of seconds in the Retry-After header, then retry. |
| QUOTA_EXCEEDED | 402 | The request would go over a limit included in your organization's plan, such as the number of quotes. The error message gives the limit. |
| VALIDATION_FAILED | 400 | The request body or query parameters are invalid. The error details list the fields that failed. |
| NOT_FOUND | 404 | No record with this ID exists in your organization. |
| CONFLICT | 409 | The request conflicts with the record's current state, for example a duplicate work order number or a change its status doesn't allow. Fetch the record and try again. |
| IDEMPOTENCY_REQUIRED | 400 | This request needs an Idempotency-Key header. Send a unique key for each operation. |
| IDEMPOTENCY_CONFLICT | 409 | This Idempotency-Key was already used with a different request body. Use a new key for a different request. |
| OWNERSHIP_REQUIRED | 400 | The record needs an owner. Send the ID of an active team member, or set a default owner on the API key. |
| EXTERNAL_REFERENCE_CONFLICT | 409 | The external reference is already linked to a different record. Look it up first, or use a different external ID. |
| SEAT_LIMIT_REACHED | 409 | Adding a schedulable team member would go over the technician seats included in your plan. An Owner or Admin must add seats in solarOS first. |
| AURORA_IDENTIFIERS_REQUIRED | 400 | The Aurora sync request is missing the Aurora design or project ID. |
| CUSTOM_FIELD_VALIDATION_FAILED | 400 | A custom field value is invalid, or the field isn't available on this record. The error message names the field. |
| UNSUPPORTED_PROJECT_TEMPLATE | 400 | This project template can't be applied through the API, for example because it needs values that come from a quote. |
| UNSUPPORTED_SORT | 400 | The sortBy or sortDir value isn't supported on this endpoint. |
| UNSUPPORTED_FILTER | 400 | A query filter isn't supported on this endpoint, or its value is invalid. |
| FUNDING_SOURCE_NOT_OFFERED | 400 | A quote's financing must be Cash or a saved financing option the quote offers. Custom terms aren't accepted. The error details name each entry and why. GET /quotes/{id}/content lists offeredFundingSources. |
| QUOTE_DESIGN_LOCKED | 409 | The quote was accepted, so its system, usage, pricing and calculation can't change. Changes after the sale go through a change order on the project. |
| INTERNAL_ERROR | 500 | Something went wrong on the solarOS side. Retry with backoff. If it keeps happening, contact solarOS support with the requestId from the response. |
Was this page helpful?